godot icon indicating copy to clipboard operation
godot copied to clipboard

Add the `[param foo]` syntax to reference parameters with a validity check

Open YuriSizov opened this issue 3 years ago • 0 comments

Closes https://github.com/godotengine/godot-proposals/issues/4880. This is based on https://github.com/godotengine/godot/pull/64004 so marking as draft for the time being.

This PR adds a new BBCode tag, [param foo] that can be used instead of the old [code]foo[/code] strings to refer to method, signal, and annotation parameters. Using them improperly, messing up names, etc. would result in CI failure in Static Check.

This should also help translators to identify that the inline code bit is a reference to a parameter instead of being a random piece of code or a reference to something else. This should hopefully let us avoid situations where we use identifiers as parts of the sentence in English and confuse translators who don't have this full context.

Neither online docs nor the built-in help have any special formatting for these new tags. They are simply displayed as code blocks. This can be adjusted with future PRs. For parity with the rest of the tag-handling code in RST generation the empty tags are stripped (both [param] and [param ]), and in built-in docs the [param] option is not handled and printed as is.

For consistency the <argument> tag in XMLs has been renamed to <param>. Note, that the engine refers to these things as arguments throughout all of its systems. But as identified by https://github.com/godotengine/godot-proposals/issues/4880, this is likely a misnomer. Doing a huge core refactor for this didn't like a good idea, but the XMLs themselves, being public-facing, should had been updated. So I did that.

Incidentally, make_rst.py already called those "params" internally, so there is that.


This PR doesn't include any usages of [param foo] yet. I'll leave to for future PR and maybe other contributors. Let's focus on the technical side here.

It's also pretty huge because of the XML changes as it is. That's why I've split it into two commits.

YuriSizov avatar Aug 06 '22 18:08 YuriSizov