boost/boostlook
2
0
Fork 0
mirror of https://github.com/boostorg/boostlook.git synced 2026-02-25 16:22:12 +00:00
Code Issues Projects Releases Wiki Activity
Files
33ce117d70197f543c1957616a233cc343d2c168
boostlook/preview/contributor-guide/docs/components.html

779 lines
29 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1">
<style>html.fonts-loading{visibility:hidden;opacity:0}</style>
<script>document.documentElement.classList.add('fonts-loading');</script>
<link rel="preload" href="../../_/font/NotoSansDisplay.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
<link rel="preload" href="../../_/font/NotoSansDisplay-Italic.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
<link rel="preload" href="../../_/font/MonaspaceNeon-Var.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
<link rel="preload" href="../../_/font/MonaspaceXenon-Var.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
<script>
(function() {
'use strict';
var revealed = false;
var reveal = function() {
if (revealed) return;
revealed = true;
document.documentElement.classList.remove('fonts-loading');
};
setTimeout(reveal, 3000);
if (!('FontFace' in window) || !('fonts' in document)) {
setTimeout(reveal, 100);
return;
}
var uiRoot = '../../_';
var fonts = [
{
family: 'Noto Sans',
url: uiRoot + '/font/NotoSansDisplay.woff2',
descriptors: { style: 'normal', weight: '100 900', stretch: '62.5% 100%' }
},
{
family: 'Noto Sans',
url: uiRoot + '/font/NotoSansDisplay-Italic.woff2',
descriptors: { style: 'italic', weight: '100 900', stretch: '62.5% 100%' }
},
{
family: 'Monaspace Neon',
url: uiRoot + '/font/MonaspaceNeon-Var.woff2',
descriptors: { style: 'normal', weight: '400' }
},
{
family: 'Monaspace Xenon',
url: uiRoot + '/font/MonaspaceXenon-Var.woff2',
descriptors: { style: 'italic', weight: '400' }
}
];
var loadPromises = fonts.map(function(f) {
try {
var face = new FontFace(f.family, 'url("' + f.url + '")', f.descriptors);
return face.load().then(function(loaded) {
document.fonts.add(loaded);
return loaded;
}).catch(function() {
return null;
});
} catch (e) {
return Promise.resolve(null);
}
});
Promise.all(loadPromises)
.then(function() {
return document.fonts.ready;
})
.then(reveal)
.catch(reveal);
})();
</script> <title>Documentation Components :: Boost Site Docs</title>
<link rel="canonical" href="https://boost.revsys.dev/contributor-guide/docs/components.html">
<link rel="prev" href="content.html">
<link rel="next" href="antora.html">
<meta name="generator" content="Antora 3.1.14">
<link rel="stylesheet" href="../../_/css/boostlook.css">
<link rel="stylesheet" href="../../_/css/site.css">
<link rel="stylesheet" href="../../_/css/vendor/tabs.css">
<script>
(function() {
if (window.self !== window.top) return;
var theme = localStorage.getItem('antora-theme');
if (!theme && window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
theme = 'dark';
}
if (theme === 'dark') document.documentElement.classList.add('dark');
})();
</script>
<script>var uiRootPath = '../../_'</script>
<link rel="icon" href="../../_/img/favicons/favicon.ico" type="image/x-icon">
<!-- Favicon configuration -->
<link rel="apple-touch-icon" sizes="180x180" href="../../_/img/favicons/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="../../_/img/favicons/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="../../_/img/favicons/favicon-16x16.png">
<link rel="manifest" href="../../_/img/favicons/site.webmanifest">
<link rel="shortcut icon" href="../../_/img/favicons/favicon.ico">
</head>
<body class="article toc2 toc-left">
<div class="boostlook">
<script type="module">import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({"startOnLoad":true});</script> <div id="header">
<div id="toc" class="nav-container toc2" data-component="contributor-guide" data-version="">
<aside class="nav">
<button class="nav-close"></button>
<div class="panels">
<div class="nav-panel-menu is-active" data-panel="menu">
<nav class="nav-menu">
<div class="title-row">
<h3 class="title"><a href="../index.html">Contributor Guide</a></h3>
<button class="theme-toggle" aria-label="Toggle dark mode" title="Toggle theme" style="display:none">
<i class="fas fa-sun theme-icon-light"></i>
<i class="fas fa-moon theme-icon-dark"></i>
</button> </div>
<ul class="nav-list">
<ul class="nav-list">
<li class="" data-depth="1">
<a class="nav-link" href="../getting-involved.html">Getting Involved</a>
</li>
<li class="" data-depth="1">
<a class="nav-link" href="../contributors-faq.html">Contributors FAQ</a>
</li>
<li class="" data-depth="1">
<span class="nav-text">Requirements</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../requirements/library-requirements.html">Library</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../requirements/license-requirements.html">License</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../requirements/portability-requirements.html">Portability</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../requirements/organization-requirements.html">Organization</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../requirements/library-metadata.html">Metadata</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Design</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../design-guide/design-best-practices.html">Best Practices</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../design-guide/headers.html">Headers</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../design-guide/backwards-compatibility.html">Backwards Compatibility</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../design-guide/separate-compilation.html">Separate Compilation</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../design-guide/dependencies.html">Dependencies</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../design-guide/borland.html">Borland Portability</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Development</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../version-control.html">Version Control</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../best-practices.html">Best Practices</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../debug-visualisers.html">Debug Visualizers</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Testing</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../testing/intro.html">Introduction</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../testing/test-policy.html">Test Policy</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../testing/boost-test-matrix.html">Test Matrix</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../testing/regression-tests.html">Local Regression Tests</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../testing/writing-tests.html">Writing Tests</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../testing/sanitizers.html">Sanitizers</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../testing/continuous-integration.html">Continuous Integration</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../testing/fuzzing.html">Fuzzing</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">The Super-Project</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../superproject/overview.html">Layout</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../superproject/getting-started.html">Getting Started</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../superproject/library-maintenance.html">Library Maintenance</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../superproject/library-workflow.html">Library Workflow</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Writing Documentation</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="layout.html">Guidelines</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="content.html">Content</a>
</li>
<li class=" is-current-page" data-depth="2">
<a class="nav-link" href="components.html">Components</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="antora.html">Antora Guide</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="asciidoc.html">AsciiDoc Style Guide</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="logo-policy-media-guide.html">Logo Policy and Media Guide</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Releases</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../release-process.html">Release Process</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../release-notes.html">Release Notes</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Contributor Community</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../contributor-community-introduction.html">Introduction</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../oversight-committee.html">Fiscal Sponsorship Committee</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../tweeting.html">Tweeting</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../site-docs-style-guide.html">Site-docs Style Guide</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Appendices</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../organization-guide.html">Organization Guide</a>
</li>
</ul>
</ul>
</ul>
</nav>
</div>
</div>
</aside>
</div>
</div> <div id="content">
<article class="doc max-width-reset">
<div class="toolbar" role="navigation">
<button class="nav-toggle"></button>
<nav class="breadcrumbs" aria-label="breadcrumbs">
<ul>
<li>
<a href="../index.html" aria-label="Home: Contributor Guide">
<svg xmlns="http://www.w3.org/2000/svg" width="1rem" height="1rem" viewBox="0 -960 960 960" fill="#000000" aria-hidden="true"><path d="M160-120v-480l320-240 320 240v480H560v-280H400v280H160Z"/></svg>
</a>
</li>
<li>Writing Documentation</li>
<li><a href="components.html">Components</a></li>
</ul>
</nav>
<div class="spirit-nav">
<a accesskey="p" href="content.html">
<span class="material-symbols-outlined" title="Previous: Content">arrow_back</span>
</a>
<a class="disabled" accesskey="u" aria-disabled="true" tabindex="-1">
<span class="material-symbols-outlined" title="Up:">arrow_upward</span>
</a>
<a accesskey="n" href="antora.html">
<span class="material-symbols-outlined" title="Next: Antora Guide">arrow_forward</span>
</a>
</div></div>
<h1 class="page">Documentation Components</h1>
<div class="sect1">
<h2 id="_introduction"><a class="anchor" href="#_introduction"></a>Introduction</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Boost does not require any specific documentation structure. However,
there are some important considerations that influence content and
structure. For example, many Boost libraries wind up being proposed for
inclusion in the C++ Standard, so writing them initially with text
suitable for inclusion in the Standard may be helpful.</p>
</div>
<div class="paragraph">
<p>Also, Boost library documentation is often accessed via the World Wide Web, including via search engines, so context is often important for every page.</p>
</div>
<div class="paragraph">
<p>Finally, Boost libraries should provide additional documentation,
such as introductory, tutorial, example, and rationale content. With
those things in mind, we suggest the following guidelines for Boost
library documentation.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_conforming_to_standards"><a class="anchor" href="#_conforming_to_standards"></a>Conforming to Standards</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The documentation structure required for the C++ Standard is an
effective way to describe the technical specifications for a library.
Although terse, that format is familiar to many Boost users and is far
more precise than most ad hoc formats. The following description is
based upon §17.3 of the Standard. (Note that while final Standard
proposals must include full standard-ese wording, which the committee
will not do for you, that level of detail is not expected of Boost
library documentation.)</p>
</div>
<div class="sect2">
<h3 id="_document_elements"><a class="anchor" href="#_document_elements"></a>Document Elements</h3>
<div id="footnote1-location" class="paragraph">
<p>Each document contains the following elements, as
applicable. <a href="#footnote1">(1)</a>:</p>
</div>
<div class="ulist disc">
<ul class="disc">
<li>
<p><a href="#_summary">Summary</a></p>
</li>
<li>
<p><a href="#_requirements">Requirements</a></p>
</li>
<li>
<p><a href="#_detailed_specifications">Detailed Specifications</a></p>
</li>
<li>
<p><a href="#_references_to_the_c_standard_library">References to the C++ Standard Library</a></p>
</li>
<li>
<p><a href="#_references_to_the_c_standard_library_2">References to the C Standard Library</a></p>
</li>
</ul>
</div>
<div class="sect3">
<h4 id="_summary"><a class="anchor" href="#_summary"></a>Summary</h4>
<div class="paragraph">
<p>The Summary provides a synopsis of the category, and introduces the
first-level subclauses. Each subclause also provides a summary, listing the headers specified in the subclause and the library entities provided in each header.</p>
</div>
<div class="paragraph">
<p>Paragraphs labeled "Note(s):" or "Example(s):" are informative, other
paragraphs are normative.</p>
</div>
<div class="paragraph">
<p>The summary and the detailed specifications are presented in the order:</p>
</div>
<div class="ulist disc">
<ul class="disc">
<li>
<p>Macros</p>
</li>
<li>
<p>Values</p>
</li>
<li>
<p>Types</p>
</li>
<li>
<p>Classes</p>
</li>
<li>
<p>Functions</p>
</li>
<li>
<p>Objects</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_requirements"><a class="anchor" href="#_requirements"></a>Requirements</h4>
<div class="paragraph">
<p>The library can be extended by a C++ program. Each clause, as
applicable, describes the requirements that such extensions must meet.
Such extensions are generally one of the following:</p>
</div>
<div class="ulist disc">
<ul class="disc">
<li>
<p>Template arguments</p>
</li>
<li>
<p>Derived classes</p>
</li>
<li>
<p>Containers, iterators, and/or algorithms that meet an interface
convention</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Interface convention requirements are stated as generally as possible.
For example, instead of stating " <code>class X</code> has to define a member function <code>operator++()</code> ", say " the interface requires for any object <code>x</code> of <code>class X</code>, <code>++x</code> is defined" (noting that whether the operator is a member or not is unspecified).</p>
</div>
<div class="paragraph">
<p>Requirements are stated in terms of well-defined expressions, which
define valid terms of the types that satisfy the requirements. For every set of requirements there is a table that specifies an initial set of
the valid expressions and their semantics. Any generic algorithm that
uses the requirements is described in terms of the valid expressions for its formal type parameters.</p>
</div>
<div class="paragraph">
<p>Template argument requirements are sometimes referenced by name.</p>
</div>
<div id="footnote2-location" class="paragraph">
<p>In some cases the semantic requirements are presented as C++ code. Such
code is intended as a specification of equivalence of a construct to
another construct, not necessarily as the way the construct must be
implemented.<a href="#footnote2">(2)</a></p>
</div>
</div>
<div class="sect3">
<h4 id="_detailed_specifications"><a class="anchor" href="#_detailed_specifications"></a>Detailed Specifications</h4>
<div class="paragraph">
<p>The detailed specifications each contain the following elements:</p>
</div>
<div class="ulist disc">
<ul class="disc">
<li>
<p>Name and brief description</p>
</li>
<li>
<p>Synopsis (class definition or function prototype, as appropriate)</p>
</li>
<li>
<p>Restrictions on template arguments, if any</p>
</li>
<li>
<p>Description of class invariants</p>
</li>
<li>
<p>Description of function semantics</p>
</li>
</ul>
</div>
<div id="footnote3-location" class="paragraph">
<p>Descriptions of class member functions follow the order (as
appropriate) <a href="#footnote3">(3)</a>:</p>
</div>
<div class="ulist disc">
<ul class="disc">
<li>
<p>Constructor(s) and destructor</p>
</li>
<li>
<p>Copying and assignment functions</p>
</li>
<li>
<p>Comparison functions</p>
</li>
<li>
<p>Modifier functions</p>
</li>
<li>
<p>Observer functions</p>
</li>
<li>
<p>Operators and other non-member functions</p>
</li>
</ul>
</div>
<div id="footnote4-location" class="paragraph">
<p>Descriptions of function semantics contain the following
elements (as appropriate) <a href="#footnote4">(4):</a></p>
</div>
<div class="ulist disc">
<ul class="disc">
<li>
<p><strong><a href="#_requires">Requires</a></strong>: the preconditions for calling the function</p>
</li>
<li>
<p><strong><a href="#_effects">Effects</a></strong>: the actions performed by the function</p>
</li>
<li>
<p><strong><a href="#_post_conditions">Post-conditions</a>"</strong>: the observable results established by the function</p>
</li>
<li>
<p><strong><a href="#_returns">Returns</a></strong>: a description of the value(s) returned by the function</p>
</li>
<li>
<p><strong><a href="#_throws">Throws</a></strong>: any exceptions thrown by the function, and the conditions that would cause the exception</p>
</li>
<li>
<p><strong><a href="#_complexity">Complexity</a></strong>: the time and/or space complexity of the function</p>
</li>
<li>
<p><strong><a href="#_rationale">Rationale</a></strong>: the rationale for the function&#8217;s design or existence</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Complexity requirements specified in the library clauses are upper bounds, and implementations that provide better complexity guarantees satisfy the requirements.</p>
</div>
</div>
<div class="sect3">
<h4 id="_references_to_the_c_standard_library"><a class="anchor" href="#_references_to_the_c_standard_library"></a>References to the C++ Standard Library</h4>
</div>
<div class="sect3">
<h4 id="_references_to_the_c_standard_library_2"><a class="anchor" href="#_references_to_the_c_standard_library_2"></a>References to the C Standard Library</h4>
</div>
</div>
<div class="sect2">
<h3 id="_other_conventions"><a class="anchor" href="#_other_conventions"></a>Other Conventions</h3>
<div class="paragraph">
<p>These conventions are for describing implementation-defined types, and member functions.</p>
</div>
<div class="sect3">
<h4 id="_type_descriptions"><a class="anchor" href="#_type_descriptions"></a>Type Descriptions</h4>
<div class="paragraph">
<p>The Requirements subclauses may describe names that are used to specify constraints on template arguments.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_more_information"><a class="anchor" href="#_more_information"></a>More Information</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_function_semantic_element_explanations"><a class="anchor" href="#_function_semantic_element_explanations"></a>Function Semantic Element Explanations</h3>
<div class="paragraph">
<p>The function semantic element description above is taken directly from the C++ standard, and is quite terse. Here is a
more detailed explanation of each of the elements.</p>
</div>
<div class="paragraph">
<p>Note the use of the <code>&lt;code&gt; &#8230;&#8203; &lt;/code&gt;</code> font tag to distinguish actual C++ usage from English prose.</p>
</div>
<div class="sect3">
<h4 id="_requires"><a class="anchor" href="#_requires"></a>Requires</h4>
<div class="paragraph">
<p>Preconditions for calling the function, typically expressed as predicates. The most common preconditions are requirements on the value of arguments, often in the form of C++ expressions. For example,</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-cpp hljs" data-lang="cpp">void limit( int * p, int min, int max );</code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>Requires:</strong> <code>p != 0 &amp;&amp; min &#8656; max</code></p>
</div>
<div class="paragraph">
<p>Requirements already enforced by the C++ language rules (such as the
type of arguments) are not repeated in Requires paragraphs.</p>
</div>
</div>
<div class="sect3">
<h4 id="_effects"><a class="anchor" href="#_effects"></a>Effects</h4>
<div class="paragraph">
<p>The actions performed by the function, described either in prose or in
C++. A description in prose is often less limiting on implementors, but
is often less precise than C++ code.</p>
</div>
<div class="paragraph">
<p>If an effect is specified in one of the other elements, particularly
<em>post-conditions</em>, <em>returns</em>, or <em>throws</em>, it is not also described in
the <em>effects</em> paragraph. Having only a single description ensures that
there is one and only one specification, and thus eliminates the risk of
divergence.</p>
</div>
</div>
<div class="sect3">
<h4 id="_post_conditions"><a class="anchor" href="#_post_conditions"></a>Post-conditions</h4>
<div class="paragraph">
<p>The observable results of the function, such as the value of variables.
Post-conditions are often expressed as predicates that are true after the
function completes, in the form of C++ expressions. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-cpp hljs" data-lang="cpp">void make_zero_if_negative( int &amp; x );</code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>Post-condition:</strong> <code>x &gt;= 0</code></p>
</div>
</div>
<div class="sect3">
<h4 id="_returns"><a class="anchor" href="#_returns"></a>Returns</h4>
<div class="paragraph">
<p>The value returned by the function, usually in the form of a C++
expression. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-cpp hljs" data-lang="cpp">int sum( int x, int y );</code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>Returns</strong>: <code>x + y</code></p>
</div>
<div class="paragraph">
<p>Only specify the return value; the type is already dictated by C++
language rules.</p>
</div>
</div>
<div class="sect3">
<h4 id="_throws"><a class="anchor" href="#_throws"></a>Throws</h4>
<div class="paragraph">
<p>Specify both the type of exception thrown, and the condition that causes
the exception to be thrown. For example, the <code>std::basic_string</code> class
specifies:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-cpp hljs" data-lang="cpp">void resize(size_type n, charT c);</code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>Throws:</strong> <code>length_error</code> if <code>n &gt; max_size()</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_complexity"><a class="anchor" href="#_complexity"></a>Complexity</h4>
<div class="paragraph">
<p>Specifying the time and/or space complexity of a function is often not
desirable because it over-constrains implementors and is hard to specify
correctly. Complexity is thus often best left as a quality of
implementation issue.</p>
</div>
<div class="paragraph">
<p>A library component, however, can become effectively non-portable if
there is wide variation in performance between conforming
implementations. Containers are a prime example. In these cases it
becomes worthwhile to specify complexity.</p>
</div>
<div class="paragraph">
<p>Complexity is often specified in generalized
<a href="https://web.mit.edu/16.070/www/lecture/big_o.pdf">"Big-O" notation</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_rationale"><a class="anchor" href="#_rationale"></a>Rationale</h4>
<div class="paragraph">
<p>Specifying the rationale for a function&#8217;s design or existence can often
give users a lot of insight into why a library is designed the way it
is. More importantly, it can help prevent "fixing" something that wasn&#8217;t
really broken as the library matures.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_web_references"><a class="anchor" href="#_web_references"></a>Web References</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Boost library documentation is often accessed via the World Web. Using
search engines, a page deep in the reference content could be viewed
without any further context. Therefore, it is helpful to add extra
context, such as the following, to each page:</p>
</div>
<div class="ulist disc">
<ul class="disc">
<li>
<p>Describe the enclosing namespace or use fully scoped identifiers.</p>
</li>
<li>
<p>Document required headers for each type or function.</p>
</li>
<li>
<p>Link to relevant tutorial information.</p>
</li>
<li>
<p>Link to related example code.</p>
</li>
<li>
<p>Include the library name.</p>
</li>
<li>
<p>Include navigation elements to the beginning of the documentation.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>It is also useful to consider the effectiveness of a description in
search engines. Terse or cryptic descriptions are less likely to help
the curious find a relevant function or type.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_footnotes"><a class="anchor" href="#_footnotes"></a>Footnotes</h2>
<div class="sectionbody">
<div id="footnote1" class="paragraph">
<p><a href="#footnote1-location">(1)</a> To save space, items that do not apply to
a clause are omitted. For example, if a clause does not specify any
requirements, there will be no "Requirements" subclause.</p>
</div>
<div id="footnote2" class="paragraph">
<p><a href="#footnote2-location">(2)</a> Although in some cases the code is
unambiguously the optimum implementation.</p>
</div>
<div id="footnote3" class="paragraph">
<p><a href="#footnote3-location">(3)</a> To save space, items that do not apply to
a class are omitted. For example, if a class does not specify any
comparison functions, there will be no "Comparison functions" subclause.</p>
</div>
<div id="footnote4" class="paragraph">
<p><a href="#footnote4-location">(4)</a> To save space, items that do not apply to
a function are omitted. For example, if a function does not specify any
precondition, there will be no "Requires" paragraph.</p>
</div>
<hr>
<div class="paragraph">
<p><em>Revised April, 2023</em></p>
</div>
<div class="paragraph">
<p><em>Distributed under the Boost Software License, Version 1.0. Refer to <a href="http://www.boost.org/LICENSE_1_0.txt" class="bare">http://www.boost.org/LICENSE_1_0.txt</a></em>.</p>
</div>
</div>
</div>
<div class="edit-this-page">
<a href="file:///Users/julio/dev/website-v2-docs/contributor-guide/modules/ROOT/pages/docs/components.adoc">Edit this Page</a>
</div>
<nav class="pagination">
<span class="prev"><a href="content.html">Content</a></span>
<span class="next"><a href="antora.html">Antora Guide</a></span>
</nav>
</article>
</div>
<div id="footer">
<script id="site-script" src="../../_/js/site.js" data-ui-root-path="../../_"></script>
<script async src="../../_/js/vendor/highlight.js"></script>
<script async src="../../_/js/vendor/tabs.js" data-sync-storage-key="preferred-tab"></script>
</div>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink