search

HaxeFoundation / haxe

Haxe - The Cross-Platform Toolkit
https://haxe.org
6.14k stars 656 forks source link

Undocumented compiler define flags #10379

Open tobil4sk opened 3 years ago

tobil4sk commented 3 years ago

There are a number of defines that are not documented on the page in the manual.

Furthermore, in the compiler code they are access via a raw string rather than a strict value, so even if some should be hidden from documentation it would be good to add them to defines.json for cleaner and slightly safer code.

Is there any reason why any of these should not be documented?

Here are the lists:

Mentioned in #7965:

These might be deprecated:

And these are related to version numbers:

Defines that are documented but don't generate automatically and are accessed internally via raw strings:

jdonaldson commented 3 years ago

Just wanted to say... I looked into this a long time ago, and came away thinking:

  1. There's not a lot of naming consistency, but all of the names of things make sense in context.
  2. You need to really know the context if you're going to use the flag properly.
  3. The context for a flag is often tied to a platform or framework, and the flag is often automatically set for you in associated build tooling... meaning a platform/framework author worries about it so that you don't have to.

Messing around with undocumented Haxe flags is really pretty dangerous IMHO, and if one wants to do something very specific that requires some kind of undocumented flag feature, one should be checking in with someone from the compiler team for advice (hop on discord, slack, etc)... almost like checking in with a park ranger before going on a long hike. Because, projects relying on certain flag behaviors can quickly turn into an unforgiving wilderness.

Aurel300 commented 3 years ago

@jdonaldson Such flags can be marked "internal" in their doc, as is already the case for some of them. Having all the defines in a single JSON document (and therefore shown in the manual) seems like an improvement.

tobil4sk commented 3 years ago

If the deprecated ones were going to be added, might be good for them to be marked as such for the documentation along with haxe --help-defines output.

Gama11 commented 3 years ago

Doesn't really make sense to "deprecate" haxe3 and haxe4 - both of those pretty much need to stay defined for all future Haxe versions. They're used as "haxe >= 3/4", so any code with backwards-compatibility checks using them would break if they were removed.

tobil4sk commented 3 years ago

I don't think any flags at all can really be removed, because even if they aren't as integral as haxe4, removing them would result in silently ignored or broken code. But it would be good in the documentation to separate the defines that are there just for backwards compatability, and perhaps give an indication of the replacement that should be used. This way in the future there won't have to be a haxe5 define for example, as it will be established in the documentation that now haxe is the more consistent long term way to check compiler versions. So maybe deprecated isn't the right word?

tobil4sk commented 3 years ago

Also: HaxeFoundation/HaxeManual/issues/413