Prevent recursive definitions or repeating names over context in class reference documentation

[Wilker-uwu]

Problem or limitation

when browsing the class references to unfamiliar tools in Godot, more often than i'm comfortable with i stumble upon method descriptions like this:

<!-- from InputMap.xml -->
<method name="get_action_description" qualifiers="const">
	<return type="String" />
	<param index="0" name="action" type="StringName" />
	<return type="String"/>
	<param index="0" name="action" type="StringName"/>
	<description>
		Returns the human-readable description of the given action.
	</description>
</method>

where in this example, if you don't have a context of what "human-readable description" entails, you might as well understand this single sentence as the method name copy-pasted as the description, sometimes vague enough to a point where looking at the engine code itself gives a better description than that sentence, and for me this can get frustrating when i don't know much c++.

Proposed improvement

include in the documentation contribution guidelines, a dedicated section describing ways to avoid non descriptive repetitions of names of elements.

documentation needs to always assume the reader had never read anything before that particular page, and repeating context can be much more helpful than repeating names only. the exercise to practice for this is in trying to make a conscious effort in defining a word, but without using the word itself, and without jumping into examples without fully defining it first.

another example also from InputMap.xml:

<method name="action_get_deadzone">
	<return type="float"/>
	<param index="0" name="action" type="StringName"/>
	<description>
		Returns a deadzone value for the action.
	</description>
</method>

the above should then become this:

<method name="action_get_deadzone">
	<return type="float"/>
	<param index="0" name="action" type="StringName"/>
	<description>
		Returns the current, minimum percentage value for the analog threshold of the given [code]action[/code] in which it activates. Analog input strengths below that value will not activate.
	</description>
</method>

it is more verbose, but is easier to understand if someone happens to encounter the concept of a deadzone for the first time in the documentation, and i should say the same about lots of words used in the engine as a whole that can and will get exposed to even people learning programming for the first time, let alone people who can program but are encountering other field vocabularies in it.

Proposal review

• Yes, this proposal is highly specific and actionable.