godot-docs icon indicating copy to clipboard operation
godot-docs copied to clipboard

Define standard referencing/formatting behavior for class and property names in classref and manual pages

Open snailrhymer opened this issue 2 years ago • 2 comments

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:

  1. When a class name should contain a link to the class ref (never/once per page/once per section/always?)
  2. How property names should be formatted (I've seen no formatting, bold, and code in use).
  3. What property name to use (consider e.g. albedo_texture in a StandardMaterial3D, which appears as "Texture" under the heading "Albedo").
  4. How inspector subsection names should be formatted (e.g. how should a tutorial instruct users to find material_override on a MeshInstance3D? 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.

snailrhymer avatar Jul 13 '22 20:07 snailrhymer

Is this report complete? If so, I don't understand what the problem is.

YuriSizov avatar Jul 13 '22 20:07 YuriSizov

No, sorry - I mispressed enter while editing the title. I'm currently writing the body of it.

Edit: Complete now

snailrhymer avatar Jul 13 '22 20:07 snailrhymer