Documenting Everything

This page contains guidelines for creating documents for various language or library entities.

Behavior

The Behavior component gives highlight colors to its content, which could be used for emphasizing keywords related to program behaviors.

import Behavior from "@components/Behavior.astro";

It is <Behavior kind="well-def">well-defined</Behavior> to do this.

It is <Behavior kind="impl-def">implementation-defined</Behavior>
how this is achieved.

It is <Behavior kind="unspec">unspecified</Behavior>
which function argument will be evaluated first.

The behavior is <Behavior kind="undef">undefined</Behavior>
to add two signed integers that overflows the result.

It is <Behavior kind="ill-formed">ill-formed</Behavior>
to use an undefined identifier.

The program is
<Behavior kind="ifndr">ill-formed no diagnostics required</Behavior>
if it violates the one-definition rule.

Preview

It is well-defined to do this.

It is implementation-defined how this is achieved.

It is unspecified which function argument will be evaluated first.

The behavior is undefined to add two signed integers that overflows the result.

It is ill-formed to use an undefined identifier.

The program is ill-formed no diagnostics required if it violates the one-definition rule.

Declaration

Basic Usage

The DeclDoc component gives brief introduction to a C/C++ declaration.

import { Decl, DeclDoc } from "@components/decl-doc";

<DeclDoc>
  <Decl slot="decl">
    ```cpp
    int main() { /* body */ }
    ```
  </Decl>

  A `main` function is the entry point of a program.
</DeclDoc>

Preview

int main() { /* body */ }

A main function running independently of environment-provided arguments.

Expand

A DeclDoc component can contain multiple Decl as well:

import { Decl, DeclDoc } from "@components/decl-doc";

<DeclDoc>
  <Decl slot="decl">
    ```cpp
    int main() { /* body */ }
    ```
  </Decl>
  <Decl slot="decl">
    ```cpp
    int main(int argc, char *argv[]) { /* body */ }
    ```
  </Decl>

  A `main` function is the entry point of a program.
</DeclDoc>

Preview

int main() { /* body */ }

int main(int argc, char *argv[]) { /* body */ }

A main function is the entry point of a program.

Expand

Specifying Revisions

You could specify revisions for each declaration with the RevisionBlock component:

import { Decl, DeclDoc } from "@components/decl-doc";
import { RevisionBlock } from "@components/revision";

<DeclDoc autorevSince="C++11">
  <Decl slot="decl">
    <RevisionBlock since="C++11" until="C++14" noborder>
      ```cpp
      template <typename T>
      typename std::remove_reference<T>::type&& move(T&& t) noexcept;
      ```
    </RevisionBlock>
  </Decl>
  <Decl slot="decl">
    <RevisionBlock since="C++14" noborder>
      ```cpp
      template <class T>
      constexpr std::remove_reference_t<T>&& move(T&& t) noexcept;
      ```
    </RevisionBlock>
  </Decl>

  `std::move` is used to _indicate_ that an object `t` may be "moved from", i.
  e. allowing the efficient transfer of resources from `t` to another object.
</DeclDoc>

Preview

template <typename T>
typename std::remove_reference<T>::type&& move(T&& t) noexcept;

(since C++11)

(until C++14)

template <class T>
constexpr std::remove_reference_t<T>&& move(T&& t) noexcept;

(since C++14)

std::move is used to indicate that an object t may be “moved from”, i. e. allowing the efficient transfer of resources from t to another object.

Expand

Tip

Don’t forget the autorevSince attribute on the DeclDoc component! Presence of this attribute allows autorev to automatically show and hide the DeclDoc component according to the user-selected revision.

Description list

Basic Usage

The DescList component is a general component for displaying a list of items and their descriptions. It could be used for listing headers, functions, classes, members, etc. while giving each of them a brief introduction.

import { DescList, Desc } from "@components/desc-list";

<DescList>
  <Desc>
    <CHeader slot="item" name="assert" />
    Conditionally compiled macro that compares its argument to zero
  </Desc>

  <Desc>
    <CHeader slot="item" name="ctype" />
    Functions to determine the type contained in character data
  </Desc>

  <Desc>
    <CHeader slot="item" name="errno" />
    Macros reporting error conditions
  </Desc>
</DescList>

Preview

<assert.h>

Conditionally compiled macro that compares its argument to zero

<ctype.h>

Functions to determine the type contained in character data

<errno.h>

Macros reporting error conditions

Specifying Revisions

You could attach revision information to each description list item with a combination of RevisionBlock and autorev attributes.

import { CHeader } from "@components/header";
import { Desc, DescList } from "@components/desc-list";
import { RevisionBlock } from "@components/revision";

<DescList>
  <Desc>
    <CHeader slot="item" name="assert" />
    Conditionally compiled macro that compares its argument to zero
  </Desc>

  <Desc autorevSince="C99">
    <RevisionBlock slot="item" noborder since="C99" vertical>
      <CHeader name="complex" />
    </RevisionBlock>
    Complex number arithmetic
  </Desc>

  <Desc>
    <CHeader slot="item" name="ctype" />
    Functions to determine the type contained in character data
  </Desc>
</DescList>

Preview

<assert.h>

Conditionally compiled macro that compares its argument to zero

<complex.h>

(since C99)

Complex number arithmetic

<ctype.h>

Functions to determine the type contained in character data

Tip

We strongly recommend you to specify the vertical attribute on the RevisionBlock component inside a Decl. This would render to a more mobile-friendly output.

Tip

Don’t forget the autorevSince attribute on the Desc component! Presence of this attribute allows autorev to automatically show and hide the Desc component according to the user-selected revision.

Parameters

The ParamDocList component can be used to document function or template parameters.

<ParamDocList>
  <ParamDoc name="argc">
    Non-negative value representing the number of arguments passed to the program.
  </ParamDoc>
  <ParamDoc name="argv">
    Pointer to the first element of an array of `argc + 1` pointers.
  </ParamDoc>
</ParamDocList>

Preview

argc

-

Non-negative value representing the number of arguments passed to the program.

argv

-

Pointer to the first element of an array of argc + 1 pointers.

Links

Link by Doc Keys

Each page could optionally associate itself with zero or more doc keys through its frontmatter.

---
title: std::move
cppdoc:
  keys: ["cpp.library.utilities.move"]
  cppdoc:
    lang: C++
    since: C++11
---

Caution

While a page can have multiple doc keys, each unique doc key can only be associated to at most one page.

The DocLink component allows you to render an inline link to the page associated with the specified doc key. You can also specify the destination page by its absolute path.

import DocLink from "@components/DocLink.astro";

Check out
<DocLink src="cpp.library.utilities.move">this page</DocLink>
for more information about `std::move`.

Check out
<DocLink src="/cpp/library/utilities/move">this page</DocLink>
for more information about `std::move`.

Preview

Check out this page for detailed information about std::move.

Check out this page for more information about std::move.

Tip

If the specified doc key does not exist yet, the DocLink component will render as a plain text span without a link.

Link to Header

The CHeader and the CppHeader component renders an inline link to the documentation page of a header file.

import { CHeader, CppHeader } from "@components/header";

<CHeader name="stdio" /> is a C standard library header.
Entities in it can be used in a C++ program by including the header
<CppHeader name="cstdio" />.

<CppHeader name="vector" /> is a C++ standard library header.

Preview

<stdio.h> is a C standard library header. Entities in it can be used in a C++ program by including the header <cstdio> .

<vector> is a C++ standard library header.

Tip

If documentation for the specified header does not exist yet, the CHeader and the CppHeader component will render the header name as plain text without a link.

Feature Test Macros

The FeatureTestMacro component renders to a box that shows information about a feature test macro.

import {
  FeatureTestMacro,
  FeatureTestMacroValue
} from "@components/feature-test-macro";

<FeatureTestMacro name="__cpp_consteval">
  <FeatureTestMacroValue value="201811L" since="C++20">
    Immediate functions
  </FeatureTestMacroValue>
  <FeatureTestMacroValue value="202211L" since="C++23">
    Making `consteval` propagate up
  </FeatureTestMacroValue>
</FeatureTestMacro>

Preview

Feature test macro __cpp_consteval

Value	Since	Feature
201811L	C++20	Immediate functions
202211L	C++23	Making consteval propagate up

Defect Reports

The DRList component shows a list of defect reports (DRs). Each defect report is rendered by a DR component.

import { DR, DRList } from "@components/defect-report";

<DRList>
  <DR kind="cwg" id={1003} std="C++98">
    <Fragment slot="behavior-published">
      supported parameter names of `main` were overly restricted
    </Fragment>
    <Fragment slot="correct-behavior">
      all valid parameter names are supported
    </Fragment>
  </DR>

  <DR kind="cwg" id={1886} std="C++98">
    <Fragment slot="behavior-published">
      the `main` function could be declared with a language linkage
    </Fragment>
    <Fragment slot="correct-behavior">
      prohibited
    </Fragment>
  </DR>

  <DR kind="cwg" id={2479} std="C++20">
    <Fragment slot="behavior-published">
      the `main` function could be declared `consteval`
    </Fragment>
    <Fragment slot="correct-behavior">
      prohibited
    </Fragment>
  </DR>
</DRList>

Preview

CWG 1003 (C++98)

Link	https://cplusplus.github.io/CWG/issues/1003.html
Applied to	C++98
Behavior as published	supported parameter names of main were overly restricted
Correct behavior	all valid parameter names are supported

CWG 1886 (C++98)

Link	https://cplusplus.github.io/CWG/issues/1886.html
Applied to	C++98
Behavior as published	the main function could be declared with a language linkage
Correct behavior	prohibited

CWG 2479 (C++20)

Link	https://cplusplus.github.io/CWG/issues/2479.html
Applied to	C++20
Behavior as published	the main function could be declared consteval
Correct behavior	prohibited

Missing Content

The Missing component could be used for marking content that is still missing.

import { Missing } from "@components/missing";

See <Missing>this page</Missing> for more information.

Preview

See this page for more information.