Help:Manual of style

This page contains a design guideline that helps to follow consistent style and formatting in this wiki. Note, that the guideline list is neither final nor complete, i.e. new guidelines can be added and the current changed if there's benefit to do that.

Page structure
Most of the pages in this wiki have the following pattern:

Title override
Title override is almost mandatory, MediaWiki displays the path of the page otherwise.

If the feature is not a member of any classes, the title is overridden directly using ctitle or cpp/title. Otherwise, a helper template that abstracts the container class name is created. For example consider :

contains

whereas contains. This helper template is used for all members of that class.

Navigation bar
Navigation bars are used to improve the navigation by providing links to relevant pages. A navigation bar is usually implemented using the navbar template. The resulting definition is usually put to.

The navbar template defines a heading which is always visible and content that is shown on hover. The definitions of both are usually put into separate templates at and  respectively.

The content is usually a list of related functions and classes. The list is usually implemented using nv family of templates.

The definition of the navigation bar includes the heading and content templates of each of its parent pages.

mark c++11 should be used in navbars instead of mark since c++11 to conserve space.

Declaration of the class or function
The declaration is put as is defined in the header. The template and parameter names are renamed according to the common names in this wiki if possible. dcl family templates are used to handle the formatting.

Description
The description usually contains a bit of text that explains the behavior of class/function/object/etc and additional information that is categorized into separate sections (see below).

The first sentence of the description text must summarize the behavior of the feature. The length of it should not exceed ~200 characters (that's about two lines of text).

Classes
The description of a class generally follows the following pattern:


 * Description text
 * Template parameters if the class is a template
 * Member types
 * Member functions
 * Member objects
 * Protected member types
 * Protected functions
 * Protected member objects
 * Non-member functions
 * Helper types
 * Helper classes
 * Notes
 * Example
 * See also

dsc template family is used to handle the formatting of lists of member types, functions or objects, as well as lists of related non-member functions or classes.

Usually the same member description bits (e.g. cpp/component/class/fun_function) would be included into See also section of other pages. To reduce the duplication, it's worth to put those bits into separate templates and then use dsc inc to include them.

For example:

In

In

... ...  ===See also===

In

If the same description bits are used across several classes, as is, e.g. in the Containers library, one template can remove duplications in as many as 20 places.

Functions
The description of a function generally follows the following pattern:


 * Description text
 * Parameters
 * Return value
 * Exceptions
 * Complexity
 * Notes
 * Possible implementation
 * Example

All parameter names are written in monospace font.

par template family is used to handle the formatting of parameter descriptions.

(none) is used to indicate absence of parameters, return value or thrown exceptions.

eq fun can be used to format equivalent code

example can be used to format examples

Object, constant, types
The description of an object, constant or type generally contains only description.

Niebloids
The description of a niebloid generally follows the same pattern as that of a function, except that the introduction should include cpp/ranges/niebloid (?)

Concepts
The description of a concept generally contains only description.

See also list
Lists the relevant functions, classes, etc. template family is used to handle the formatting.

Capitalization
Names are capitalized in the same way as in most of the C++ standard. The documentation of the standard components should follow the following style:
 * function parameters use style
 * template parameters use style

In examples and other documentation, the following additional guidelines apply:
 * custom class names use style
 * variable names use style
 * macro and constant names use style

Spacing and indentation

 * K&R indentation style is used (see K&R TBS).
 * Standard constructs, i.e., , , etc have a space between identifier and opening parentheses, e.g..
 * There is no space between function name and the parentheses, as well as between the parentheses and the content between them, e.g..
 * There is no space between template name and symbol, as well as between  and  symbols and the template parameters, e.g..
 * Multiple function or template parameters are separated by space after the comma.
 * There is no space between reference and pointer ( and ) modifiers and the type name (e.g. int& b).
 * If the parameters of a function span several lines, the indentation of all parameters matches the opening parenthesis. The same goes for template parameters.

For example:

Not all of these rules apply for the detailed feature declarations (those going into template), since extra readability is needed. The exceptions include:
 * There is space between the and  symbols and template parameters for function templates.
 * Class templates have their parameters laid out through several lines.
 * For function parameters, that are templates, there are no spaces between the and  symbols and the template parameters. Also, there is no space after the comma separating the template parameters.

For example: