| title | Documenting Everything | ||
|---|---|---|---|
| sidebar |
|
import { Aside, Card, Code } from "@astrojs/starlight/components"; import Behavior from "@components/Behavior.astro"; import { CHeader, CppHeader } from "@components/header"; import { Decl, DeclDoc } from "@components/decl-doc"; import { Desc, DescList } from "@components/desc-list"; import DocLink from "@components/DocLink.astro"; import { DR, DRList } from "@components/defect-report"; import { FeatureTestMacro, FeatureTestMacroValue } from "@components/feature-test-macro"; import Missing from "@components/Missing.astro"; import { ParamDoc, ParamDocList } from "@components/param-doc"; import { RevisionBlock } from "@components/revision";
This page contains guidelines for creating documents for various language or library entities.
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.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.
The DeclDoc component gives brief introduction to a C/C++ declaration.
import declDocExample1 from "@src/assets/examples/development/guide/decl-doc-1.mdx?raw";
```cpp
int main() { /* body */ }
```
A `main` function running independently of environment-provided arguments.
A DeclDoc component can contain multiple Decl as well:
import declDocExample2 from "@src/assets/examples/development/guide/decl-doc-2.mdx?raw";
```cpp
int main() { /* body */ }
```
```cpp
int main(int argc, char *argv[]) { /* body */ }
```
A `main` function is the entry point of a program.
You could specify revisions for each declaration with the RevisionBlock component:
import declDocExample3 from "@src/assets/examples/development/guide/decl-doc-3.mdx?raw";
```cpp
template
typename std::remove_reference::type&& move(T&& t) noexcept;
```
```cpp
template
constexpr std::remove_reference_t&& move(T&& t) noexcept;
```
`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.
Don't forget the `autorevSince` attribute on the `DeclDoc` component! Presence of this attribute allows [autorev](./revision#autorev) to automatically show and hide the `DeclDoc` component according to the user-selected revision.
Special comments can be embedded within Markdown code blocks to specify part of codes has special meanings. Enable this feature by adding cxx-mark after the language name of code block's opening fence:
import cxxMarkExample1 from "@src/assets/examples/development/guide/cxx-mark-1.mdx?raw";
```cpp cxx-mark
// syntax of for statement
/*$s:attr*//*$opt*/ for ( /*$s:init-statement*/ /*$s:condition*//*$opt*/ ; /*$s:expression*//*$opt*/ ) /*$s:statement*/
// exposition only alias template of conditionally const type
template< bool Const, class T >
using /$e:maybe-const/ = std::conditional_t<Const, const T, T>;
</Card>
Three kinds of markers are supported:
<DeclDoc>
<Decl slot="decl">
```
/*$s:something*/
```
</Decl>
Marks part of code to be a syntax notation.
Rendered as:
```cpp cxx-mark
/*$s:something*/
```
/*$e:something*/
```
Marks part of code to be exposition only.
Rendered as:
/*$e:something*/
```
something/*$opt*/
```
Mark the previous part of code (often a syntax notation) to be optional.
Rendered as:
something/*$opt*/
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>
Conditionally compiled macro that compares its argument to zero
<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>
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>
Conditionally compiled macro that compares its argument to zero
<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>
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.
Don't forget the `autorevSince` attribute on the `Desc` component! Presence of this attribute allows [autorev](./revision#autorev) to automatically show and hide the `Desc` component according to the user-selected revision.
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>
Non-negative value representing the number of arguments passed to the program.
Pointer to the first element of an array of `argc + 1` pointers.
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
---
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`.
Check out this page for detailed information about `std::move`.
Check out this page for more information about std::move.
If the specified doc key does not exist yet, the `DocLink` component will render as a plain text span without a link.
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.
is a C standard library header. Entities in it can be used in a C++ program by including the header .
is a C++ standard library header.
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.
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>
Immediate functions
Making `consteval` propagate up
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>
supported parameter names of `main` were overly restricted
all valid parameter names are supported
<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>
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.
See this page for more information.