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!

GeneralEdit

Referencing entitiesEdit

When referring to a concept that exists in code, such as a class, function, or parameter, always reference it exactly like in the code.

Use quotes if its name starts in lowercase, so to avoid grammatical ambiguity.

  Yes
use OutputPage with the 'other' flag set.
  No
use output page with the Other flag set.

Titles and headingsEdit

Use sentence case for all headings and page titles.

Doc blocksEdit

Describing methodsEdit

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.

  Yes
/**
 * Get the RevisionRecord for the current page title.
 *
 * Also, did you know that the sun bear is the
 * smallest of all bear species?
 *
 * @return RevisionRecord
 */
  No
/**
 * This returns the RevisionRecord for the current page title.
 * Also, did you know that the sun bear is the
 * smallest of all bear species?
 *
 * @return RevisionRecord
 */

/**
 * The RevisionRecord for the current page title.
 * Also, did you know that the sun bear is the
 * smallest of all bear species?
 *
 * @return RevisionRecord
 */

Describing parametersEdit

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.

One can think of the parameter doc as a table with three columns: "type", "name", and "description". They do not form a continuous sentence, and in visuations the name and description may be rendered separately from each other (e.g. IDE tooltip, JSDoc or Doxygen output).

  Yes
@param string[] $dependencies List of modules that mediawiki.ForeignApi should depend on
  No
@param string[] $dependencies a list of modules that mediawiki.ForeignApi should depend on

@param string[] $dependencies that mediawiki.ForeignApi should depend on

Text filesEdit

Developers can keep documentation files in Git alongside code. These are generally placed in a /docs directory, or as the README.md file in a component's subdirectory.

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 {{git file}} template. For example: docs/contenthandler.md.

See alsoEdit

Further reading & InspirationEdit