Help:Templates

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.

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.

• Sidebar. Improves navigation

• 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 and a list of member objects.
• 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 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.

Sidebar

Sidebars 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.

It is easy to notice that all members of std::vector will have exactly the same sidebars. Also, the section describing links to the members of the C++ Standard Library would be extensively duplicated, as would the section with links to the members of the Containers library. The solutions for each of these problems are as follows:

• Members of the same class share a common sidebar definition. A helper template is created for that, which is included in each of these member pages. The sidebar usually resides at Template:path/to/class/class_name/sidebar, e.g. Template:cpp/container/vector/sidebar

• The links to the members of each library component are put into a separate template. Since the backend template {{sidebar}} needs a template for both heading and the content, two templates are created: Template:path/to/component/component_name/sidebar heading and Template:path/to/component/component_name/sidebar content. So for example Containers library (at cpp/container) would include its heading at Template:cpp/container/sidebar heading and Template:cpp/container/sidebar content. Now the Template:cpp/container/vector/sidebar can be composed from the templates like the following:

 
  {{sidebar
  |title        = {{cpp/sidebar heading}}
  |headingstyle = {{cpp/sidebar heading style}}
  |contentstyle = {{cpp/sidebar content style}}
  |content1 = {{cpp/sidebar content}}
  |heading2 = {{cpp/container/sidebar heading}}
  |content2 = {{cpp/container/sidebar content}}
  |heading3 = {{cpp/container/vector/sidebar heading}}
  |content3 = {{cpp/container/vector/sidebar content}}
  }}
  

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.

{{tdcl list ...}} template family is used to handle the formatting of member type lists.

{{dcl list ...}} template family is used to handle the formatting of member function/object list.

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 {{tdcl list template}} or {{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 cpp}} can be used to format equivalent code

{{example cpp}} 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