godot-docs
godot-docs copied to clipboard
Define standard referencing/formatting behavior for class and property names in classref and manual pages
Your Godot version: Latest
Issue description:
In the class refs, class/method/property names are always linked as a reference.
It would be good to make this convention clear, say by adding a line to contributing to the class refs/ that the relevant tags should always be used for class/method/property names.
For manual pages, there doesn't seem to be an established convention. It is unclear:
- When a class name should contain a link to the class ref (never/once per page/once per section/always?)
- How property names should be formatted (I've seen no formatting, bold, and
code
in use). -
What property name to use (consider e.g.
albedo_texture
in aStandardMaterial3D
, which appears as "Texture" under the heading "Albedo"). - How inspector subsection names should be formatted (e.g. how should a tutorial instruct users to find
material_override
on aMeshInstance3D
? It's under the "Geometry" subheading, under "GeometryInstance3D").
Consistency will make the docs feel more cohesive, and allow users to gain familiarity with how the docs relate to the editor/engine.
Establishing this convention clearly will also help contributors, particularly new ones - currently I have to scan through the manual until I can find a representation of the behavior I need (e.g. how property names are formatted). Having all this information in one place (as a new section in docs_writing_guidelines, say) would reduce the need for this.
Is this report complete? If so, I don't understand what the problem is.
No, sorry - I mispressed enter while editing the title. I'm currently writing the body of it.
Edit: Complete now