Namespaces
Variants
Views
Actions

Help:Templates

From cppreference.com
Revision as of 03:48, 8 August 2012 by P12 (Talk | contribs)

This page describes the template system in this wiki.

Templates provide means to achieve the following objectives:

  1. Quality. It becomes easy to modify the content and hence to fix errors. Duplicated content needs to be edited only once.
  2. Consistency. Templates make the right way to do things implicit.
  3. Usability. Advanced formatting is made easy by the templates.

There are a lot of templates in this wiki. The list of all templates is available at Special:AllPages. Since this wiki uses Mediawiki CMS, all templates present in the Wikipedia project can be used here. As an additional benefit, the template documentation can be used to learn Mediawiki template syntax.

As most of the templates are intended to be used as page building blocks, the following documentation covers the structure of the pages also.

Contents

Page structure

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

  • Title override. Almost mandatory, mediawiki displays the path of the page otherwise.
  • Navbar. Adds useful navigation links.
  • Declaration of the feature. The same as the declaration in the header file.
  • Description of the feature. The content depends on the type of the feature being described:
  • Class descriptions contain a list of member types, a list of member functions, a list of member objects and a list of related non-member functions.
  • Function descriptions contain specification of the behavior, parameters, return value, possible exceptions, etc.
  • Object/constant/type descriptions contain a short characterization of the feature and where it is used.
  • See also list. Lists relevant classes, functions, etc.

features

Title override

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 std::class::func():

cpp/blah/class/erase contains {{cpp/blah/class/title|func}}

whereas Template:cpp/blah/class/title contains {{cpp/title|n=class|{{{1}}}}}. This helper template is used for all members of that class.

Navbar

Navigation bars are used to improve the navigation by providing links to relevant pages. Since the structure of the Standard Library is quite hierarchical, links are provided to the relevant components of each level of the hierarchy.

For example, consider std::vector::erase(). The path through the library hierarchy can be roughly defined as [C++ Standard Library]->[Containers library]->[std::vector]->[erase()]. That means the sidebar for this function will contain links to all members of C++ Standard Library, all members of the Containers library and all members of std::vector.

Declaration

The declaration is put as is defined in header. The template and parameter names are renamed according to the common names in this wiki if possible. {{ddcl list ...}} templates are used to handle the formatting.

Definition

Classes

The class definition consists of short introduction and listing of all members.

{{dcl list ...}} 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. {{dcl list mem fun| cpp/component/class/fun_function| description of the function}}) would be included into See also section of several member function, thus being duplicated quite a lot. Therefore it's better to put those bits into separate templates and then use {{dcl list template}} to include them.

For example:

In cpp/component/class

 
  {{dcl list begin}}
  {{dcl list h1 | Member functions}}
  {{dcl list template | cpp/component/class/dcl list fun_function}}
  {{dcl list end}}
  

In cpp/component/class/another_function

 
  ...
  ...
  {{see also}}
  {{dcl list begin}}
  {{dcl list template | cpp/component/class/dcl list fun_function}}
  {{dcl list end}}
  

In Template:cpp/component/class/dcl list fun_function

 
  {{dcl list mem fun | cpp/component/class/fun_function | description of the function}}
  

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

Definitions of functions generally follow the following pattern:

  • Short description
  • Parameters
  • Return value
  • Exceptions
  • Complexity
  • Equivalent function
  • Example

All parameter names are written in monospace font.

{{param list ...}} 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

See also list

Lists the relevant functions, classes, etc. {{dcl list ...}} template family is used to handle the formatting.

See also

Help:Templates by category