Manual:Coding conventions/Documentation

This is a working draft of a set of conventions for writing documentation. This applies to doc-blocks in code, Markdown files, release notes, and commit messages.

Additions welcome!

Referencing entities
When referring to a class, function, parameter option, or other entity that exists in code, always reference it exactly like in the code. Use quotes if it starts in lowercase, to avoid grammatical ambiguity. For example "use OutputPage with the 'other' flag set.", as opposed to "use 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.

Text files
Developers can keep documentation files in Git alongside code. These are generally placed in a  directory.

These files are well-suited for detailed documentation about a project's code architecture, database design, etc. These can be updated together with the code in commits that change their behavior. You can link to such Git files on mediawiki.org wiki pages using the  template. For example:.

Further reading & Inspiration

 * WordPress: JavaScript Documentation Standard
 * WordPress: PHP Doc Standard