Manuel:Conventions de codage/Documentation

Cette page est actuellement une ébauche. Vous trouverez éventuellement sur la page de discussion plus d'informations ainsi que les commentaires relatifs aux modifications apportées.

Ceci est un projet d'un ensemble de conventions pour écrire de la documentation. Cela s'applique aux blocs de documentation dans le code, aux fichiers Markdown, aux notes de version et aux messages de validation.

Les additions sont bienvenues !

Quand vous faites référence à un concept qui existe dans le code, comme une classe, une fonction, ou un paramètre, présentez-le toujours exactement comme dans le code.

Utilisez des guillemets si le nom commence par une minuscule, pour éviter les ambiguïtés grammaticales.

Yes

use OutputPage with the 'other' flag set.

No

use output page with the Other flag set.

Use sentence case for all headings and page titles.

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 an empty line form the first line. The first line, when properly separated this way, is used as the method's short description in documentation pages, IDEs, tooltips, and other processors of documentation comments. Without it, the method may be presented without a description, or with the entire first paragraph fitted into the brief description.

Yes

/**
 * Get the RevisionRecord for the current page.
 *
 * 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.
 * 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
 */

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 X depends on

No

@param string[] $dependencies a list of X modules that X depends on

@param string[] $dependencies that the X module depends on

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.

• Manual:Coding conventions#Documentation
• Manual:Coding conventions/PHP#Comments and documentation
• Manual:Coding conventions/JavaScript#Documentation
• Documentation/Style guide

• WordPress: JavaScript Documentation Standard
• WordPress: PHP Doc Standard