Add syntax for documenting booleans: [true] and [false]

[Mickeon]

Describe the project you are working on

Taking a look around the raw Documentation files.

Describe the problem or limitation you are having in your project

I've noticed that very, very frequently the documentation uses the following

• "If [code]true[/code], texture is flipped horizontally".
• "If [param owned] is [code]true[/code], this method only finds nodes who have an assigned [member Node.owner]."
• "If [param include_internal] is [code]false[/code], the index won't take internal children into account,"
• "Used to chain two [Tweener]s after [method set_parallel] is called with [code]true[/code]."
• "Returns [code]true[/code] if the [Tween] still has [Tweener]s that haven't finished."

It's like a bit of a secret rule: whenever true or false is mentioned in a boolean context, surround it with [code]. Despite being everywhere, I'm surprised it doesn't have its own special syntax. Recently, parameters have received their own [param] syntax across the entire documentation, replacing their previously used [code], as well. It opened the door for more streamlined documentation.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

Allow writing [true] and [false] as valid documentation, and replace the currently existing [code]true/false[/code]. These could display like [code] at first, but in the future they may have, for example, their own color, similar to the Script Editor's.

Alternatively, give some special highlighting to true and false whenever they're surrounded by code blocks.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

• "If [param owned] is [true], this method only finds nodes who have an assigned [member Node.owner]."
• "If [param include_internal] is [false], the index won't take internal children into account,"
• "Returns [true] if the [Tween] still has [Tweener]s that haven't finished."

If this enhancement will not be used often, can it be worked around with a few lines of script?

It cannot. It's something intrinsic to the engine.

Is there a reason why this should be core and not an add-on in the asset library?

The documentation code is core.

[YuriSizov]

It's like a bit of a secret rule: whenever true or false is mentioned in a boolean context, surround it with [code]. Despite being everywhere, I'm surprised it doesn't have its own special syntax.

There is no secret rule, it applies to all literals, be it true, false, null, numbers, quoted strings, etc. Adding special syntax for true, false, and null seems tempting, but it also doesn't bring much to the table, since there is no special case and nothing to link for them.

[Mickeon]

That's true. It's mostly for "bolder", more interesting visualization, and making it easier to read and write for the developers behind the scenes.

[dalexeev]

Another option is to use [[x]] as shorthand for [code]x[/code] (in simple cases):

If [param owned] is [[true]], this method only finds nodes who have an assigned [member Node.owner].
If [param include_internal] is [[false]], the index won't take internal children into account,
Returns the floating-point remainder of [[x/y]], keeping the sign of [param x].
For the integer remainder operation, use the [[%]] operator.
Equivalent of doing [[int(x)]].

[timothyqiu]

To be honest, I don't think this is a good idea.

Changing [code]input[/code] to [param input] clarified the semantics (it adds metadata that could not be expressed with [code]). But changing [code]true[/code] to [true] is merely fewer keys to type and allows for a better appearance.

Keeping BBCode compatibility as much as possible can make better use of existing linting facilities in many editors.

[Calinou]

To add to @timothyqiu's concern, remember that third-party programs reading the class reference XML (such as LSP clients) also have to interpret the new keywords to render them correctly. Most of them have [code] replacements in place already, but not [true] or [false].

[Mickeon]

About that, you can make the same argument about class names which are formatted just the same way. It's not [class AnimatedSprite2D], it's [AnimatedSprite2D]. true, false, and null cannot ever refer to anything else but those values. Having to directly mention them is just as, if not more common than a class declaration.

[AThousandShips]

But the difference is that these literals are not documented, so having [true] would be misleading IMO as all other tags that are [something] or [type something] are refs (excepting param granted), not just formatting

I'd also say it'd be confusing that true/false/null are different from any other literal value, like why would you type [code]5[/code] but not [code]true[/code]?

[Mickeon]

Sorry for being stubborn on this but I seriously believe aiming for this, instead of writing down all consistent patterns presents class reference. Writing these values inside code tags seriously is way too standardized for there not to be a shortcut of some kind.
It's the same reason as to why I heavily champion for [note], [warning], [important] and [tip], aside from the additional formatting that these tags could benefit from, too.

I reiterate the original feeling of this proposal, that is, it is so much more comfortable to contribute to the class reference with [true], over [code]true[/code].

[tetrapod00]

I'll chime in that this is clearly, self-evidently the better syntax for humans to read and write the class reference, but I'm still not sure it's worth the compatibility loss with other applications. I also quite like dalexeev's [[literal]] proposal, but would it not have the same problems?

[Mickeon]

I'm starting to warm up to the idea of [[literal]], but instead of being a pure shorthand replacing [code] tags, it could imply the nested string is a value used by the engine/GDScript. This would not only be more encompassing than this proposal, but allow for the values inside to be interpreted and link to their corresponding class reference, perhaps even with proper highlighting.
Or, to put it briefly with examples:
"[[2]] [[0.5]] [[Vector2(0, 0)]] [[Color()]] [["unknown"]]" becomes "2 0.5 Vector2(0, 0) Color() "unknown""

This comes at the cost of being a huge, and questionable effort to code, in practice. In comparison, true, false, and null are constant words and very easy to interpret as a result.