Manual:Coding conventions/Documentation

This is a working draft of a set of conventions for writing code comments. Additions welcome!

Referencing entities
When referring to a parameter option, class or other entity that exists in code, reference it exactly like in the code, and use quotes if it starts in lowercase to avoid ambiguity. For example "a thing with OutputPage and with the 'other' flag set.", as opposed to "a thing with output page with the Other flag set."

Describing methods
When documenting a method, the first line should use the imperative mood to describe in one sentence what the method does. Additional text is optional, but if present is separated by a new line.

Describing parameters
When writing a parameter description, start with a capital letter and leave out "a" or "the" at the beginning of the description. Include a period at the end only if the description includes multiple sentences.