docs/react-wiki-archive/Commenting-conventions.md
We use tooling to convert comments in code to documentation. Please follow the conventions below when writing public facing API comments.
First take a look here on general guidance in tone, inclusion, etc:
https://docs.microsoft.com/en-us/style-guide/welcome/
When writing public facing comments, think like the consumer, not like the developer writing code. Ask yourself, why would I use this property/method?
Don't be too verbose. Try to convey purpose in the a single sentence, and only use multiple sentences if you need to.
When referring to other types in comments, use cross-linking:
Defines the {@link #Foo | `Foo`} component to use in the slot.
Defines the uncontrolled default value to use. See {@link #value | `value`} for providing a controlled value.
When cross-linking isn't available but you are still referencing a code construct, use backticks to format the construct using monospace formatting, which helps communicate the differentiation.
Props should start with a verb of what they do. Typically props "define" a value, but they can also "disable" a feature or
Good:
Defines the horizontal alignment for immediately descending child elements.
Bad:
Horizontal alignment.
Horizontal alignment of children.
Read-only getter property comments start with "Gets":
Gets the current value of the input element.
While properties with getters and setters start with "Gets/sets":
Gets/sets the current value of the input element.
Methods typically do things. Start the comment with a verb, indicating what it does. If it "does its best to do a thing in the current context", it "Attempts" to do something.
Examples:
Attempts to force capture of the mouse to this element.
Attempts to set focus to this element.
Scrolls content by one logical unit to the left.
Defines the parent-child relationship between two visuals.