mirror of
https://github.com/boostorg/more.git
synced 2024-12-25 23:20:12 +08:00
462 lines
16 KiB
HTML
462 lines
16 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<link rel="stylesheet" type="text/css" href="../../boost.css">
|
|
|
|
<title>Writing Documentation for Boost - Documentation Structure</title>
|
|
</head>
|
|
|
|
<body link="#0000FF" vlink="#800080">
|
|
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
|
|
"header">
|
|
<tr>
|
|
<td valign="top" width="300">
|
|
<h3><a href="index.html"><img height="86" width="277" alt="C++ Boost"
|
|
src="../../boost.png" border="0"></a></h3>
|
|
</td>
|
|
|
|
<td valign="top">
|
|
<h1 align="center">Writing Documentation for Boost</h1>
|
|
|
|
<h2 align="center">Documentation Structure</h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
|
|
<dl class="page-index">
|
|
<dt><a href="#introduction">Introduction</a></dt>
|
|
|
|
<dt><a href="#standards-conforming">Standards Conforming
|
|
Documentation</a></dt>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href="#elements">Document elements</a></dt>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href="#summary">Summary</a></dt>
|
|
|
|
<dt><a href="#requirements">Requirements</a></dt>
|
|
|
|
<dt><a href="#detailed-specs">Detailed specifications</a></dt>
|
|
|
|
<dt><a href="#ref-cpp">References to the Standard C++
|
|
library</a></dt>
|
|
|
|
<dt><a href="#ref-c">References to the Standard C
|
|
library</a></dt>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><a href="#other">Other conventions</a></dt>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href="#type-descs">Type descriptions</a></dt>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><a href="#more">More Information</a></dt>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href="#function-semantic-explanations">Function semantic
|
|
element explanations</a></dt>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href="#requires">Requires</a></dt>
|
|
|
|
<dt><a href="#effects">Effects</a></dt>
|
|
|
|
<dt><a href="#postconditions">Postconditions</a></dt>
|
|
|
|
<dt><a href="#returns">Returns</a></dt>
|
|
|
|
<dt><a href="#throws">Throws</a></dt>
|
|
|
|
<dt><a href="#complexity">Complexity</a></dt>
|
|
|
|
<dt><a href="#rationale">Rationale</a></dt>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><a href="#web">Web Reference Documentation</a></dt>
|
|
|
|
<dt><a href="#footnotes">Footnotes</a></dt>
|
|
</dl>
|
|
|
|
<h2><a name="introduction" id="introduction">Introduction</a></h2>
|
|
|
|
<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. Also, Boost library
|
|
documentation is often accessed via the World Wide Web,
|
|
including via search engines, so context is often important
|
|
for every page. 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>
|
|
|
|
<h2><a name="standards-conforming" id="standards-conforming">Standards
|
|
Conforming</a> Documentation</h2>
|
|
|
|
<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 standardese wording, which the committee will
|
|
not do for you, that level of detail is not expected of Boost
|
|
library documentation.)</p>
|
|
|
|
<h3><a name="elements" id="elements">Document elements</a></h3>
|
|
|
|
<p>Each document contains the following elements, as applicable<a class=
|
|
"footnote" href="#footnote1" id="footnote1-location">(1)</a>:</p>
|
|
|
|
<ul>
|
|
<li><a href="#summary">Summary</a></li>
|
|
|
|
<li><a href="#requirements">Requirements</a></li>
|
|
|
|
<li><a href="#detailed-specs">Detailed specifications</a></li>
|
|
|
|
<li><a href="#ref-cpp">References to the Standard C++ library</a></li>
|
|
|
|
<li><a href="#ref-c">References to the Standard C library</a></li>
|
|
</ul>
|
|
|
|
<h4><a name="summary" id="summary">Summary</a></h4>
|
|
|
|
<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>
|
|
|
|
<p>Paragraphs labeled "Note(s):" or "Example(s):" are informative, other
|
|
paragraphs are normative.</p>
|
|
|
|
<p>The summary and the detailed specifications are presented in the
|
|
order:</p>
|
|
|
|
<ul>
|
|
<li>Macros</li>
|
|
|
|
<li>Values</li>
|
|
|
|
<li>Types</li>
|
|
|
|
<li>Classes</li>
|
|
|
|
<li>Functions</li>
|
|
|
|
<li>Objects</li>
|
|
</ul>
|
|
|
|
<h4><a name="requirements" id="requirements">Requirements</a></h4>
|
|
|
|
<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>
|
|
|
|
<ul>
|
|
<li>Template arguments</li>
|
|
|
|
<li>Derived classes</li>
|
|
|
|
<li>Containers, iterators, and/or algorithms that meet an interface
|
|
convention</li>
|
|
</ul>
|
|
|
|
<p>Interface convention requirements are stated as generally as possible.
|
|
Instead of stating "<code>class X</code> has to define a member function
|
|
<code>operator++()</code>," the interface requires "for any object
|
|
<code>x</code> of <code>class X</code>, <code>++x</code> is defined." That
|
|
is, whether the operator is a member is unspecified.</p>
|
|
|
|
<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>
|
|
|
|
<p>Template argument requirements are sometimes referenced by name.</p>
|
|
|
|
<p>In some cases the semantic requirements are presented as C++ code. Such
|
|
code is intended as a specification of equivalance of a construct to
|
|
another construct, not necessarily as the way the construct must be
|
|
implemented.<a class="footnote" href="#footnote2" id="footnote2-location">(2)</a></p>
|
|
|
|
<h4><a name="detailed-specs" id="detailed-specs">Detailed
|
|
specification</a></h4>
|
|
|
|
<p>The detailed specifications each contain the following elements:</p>
|
|
|
|
<ul>
|
|
<li>Name and brief description</li>
|
|
|
|
<li>Synopsis (class definition or function prototype, as
|
|
appropriate)</li>
|
|
|
|
<li>Restrictions on template arguments, if any</li>
|
|
|
|
<li>Description of class invariants</li>
|
|
|
|
<li>Description of function semantics</li>
|
|
</ul>
|
|
|
|
<p>Descriptions of class member functions follow the order (as
|
|
appropriate)<a class="footnote" href="#footnote3" id="footnote3-location">(3)</a>:</p>
|
|
|
|
<ul>
|
|
<li>Constructor(s) and destructor</li>
|
|
|
|
<li>Copying and assignment functions</li>
|
|
|
|
<li>Comparison functions</li>
|
|
|
|
<li>Modifier functions</li>
|
|
|
|
<li>Observer functions</li>
|
|
|
|
<li>Operators and other non-member functions</li>
|
|
</ul>
|
|
|
|
<p>Descriptions of function semantics contain the following <a name=
|
|
"function-elements" id="function-elements">elements</a> (as
|
|
appropriate)<a class="footnote" href="#footnote4" id="footnote4-location">(4):</a></p>
|
|
|
|
<dl class="function-semantics">
|
|
<dt><b><a href="#requires">Requires:</a></b> the preconditions for
|
|
calling the function</dt>
|
|
|
|
<dt><b><a href="#effects">Effects:</a></b> the actions performed by the
|
|
function</dt>
|
|
|
|
<dt><b><a href="#postconditions">Postconditions:</a></b> the observable
|
|
results established by the function</dt>
|
|
|
|
<dt><b><a href="#returns">Returns:</a></b> a description of the value(s)
|
|
returned by the function</dt>
|
|
|
|
<dt><b><a href="#throws">Throws:</a></b> any exceptions thrown by the
|
|
function, and the conditions that would cause the exception</dt>
|
|
|
|
<dt><b><a href="#complexity">Complexity:</a></b> the time and/or space
|
|
complexity of the function</dt>
|
|
|
|
<dt><b><a href="#rationale">Rationale:</a></b> the rationale for the
|
|
function's design or existence</dt>
|
|
</dl>
|
|
|
|
<p>Complexity requirements specified in the library clauses are upper
|
|
bounds, and implementations that provide better complexity guarantees
|
|
satisfy the requirements.</p>
|
|
|
|
<h4><a name="ref-cpp" id="ref-cpp">References to the C++ Standard
|
|
library</a></h4>
|
|
|
|
<h4><a name="ref-c" id="ref-c">References to the C Standard
|
|
library</a></h4>
|
|
|
|
<h3><a name="other" id="other">Other conventions</a></h3>
|
|
|
|
<p>These conventions are for describing implementation-defined types, and
|
|
member functions.</p>
|
|
|
|
<h4><a name="type-descs" id="type-descs">Type descriptions</a></h4>
|
|
|
|
<p>The Requirements subclauses may describe names that are used to specify
|
|
constraints on template arguments.</p>
|
|
|
|
<h2><a name="more" id="more">More Information</a></h2>
|
|
|
|
<h3><a name="function-semantic-explanations" id=
|
|
"function-semantic-explanations">Function semantic element
|
|
explanations</a></h3>
|
|
|
|
<p>The function semantic element description <a href=
|
|
"#function-elements">above</a> is taken directly from the C++ standard, and
|
|
is quite terse. Here is a more detailed explanation of each of the
|
|
elements.</p>
|
|
|
|
<p>Note the use of the <code><code> ... </code></code> font tag
|
|
to distinguish actual C++ usage from English prose.</p>
|
|
|
|
<h4><a name="requires" id="requires">Requires</a></h4>
|
|
|
|
<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>
|
|
<pre>
|
|
|
|
<code>void limit( int * p, int min, int max );</code>
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
<dt><b>Requires:</b> <code>p != 0 && min <= max</code></dt>
|
|
</dl>
|
|
|
|
<p>Requirements already enforced by the C++ language rules (such as the
|
|
type of arguments) are not repeated in Requires paragraphs.</p>
|
|
|
|
<h4><a name="effects" id="effects">Effects</a></h4>
|
|
|
|
<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>
|
|
|
|
<p>If an effect is specified in one of the other elements, particularly
|
|
<i>postconditions</i>, <i>returns</i>, or <i>throws</i>, it is not also
|
|
described in the <i>effects</i> paragraph. Having only a single description
|
|
ensures that there is one and only one specification, and thus eliminates
|
|
the risk of divergence.</p>
|
|
|
|
<h4><a name="postconditions" id="postconditions">Postconditions</a></h4>
|
|
|
|
<p>The observable results of the function, such as the value of variables.
|
|
Postconditions are often expressed as predicates that are true after the
|
|
function completes, in the form of C++ expressions. For example:</p>
|
|
<pre>
|
|
|
|
void make_zero_if_negative( int & x );
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
<dt><b>Postcondition:</b> <code>x >= 0</code></dt>
|
|
</dl>
|
|
|
|
<h4><a name="returns" id="returns">Returns</a></h4>
|
|
|
|
<p>The value returned by the function, usually in the form of a C++
|
|
expression. For example:</p>
|
|
<pre>
|
|
int sum( int x, int y );
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
<dt><b>Returns:</b> <code>x + y</code></dt>
|
|
</dl>
|
|
|
|
<p>Only specify the return value; the type is already dictated by C++
|
|
language rules.</p>
|
|
|
|
<h4><a name="throws" id="throws">Throws</a></h4>
|
|
|
|
<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>
|
|
<pre>
|
|
|
|
void resize(size_type n, charT c);
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
<dt><b>Throws:</b> <code>length_error</code> if <code>n >
|
|
max_size()</code>.</dt>
|
|
</dl>
|
|
|
|
<h4><a name="complexity" id="complexity">Complexity</a></h4>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<p>Complexity is often specified in generalized <a href=
|
|
"http://hissa.nist.gov/dads/HTML/bigOnotation.html">"Big-O"
|
|
notation</a>.</p>
|
|
|
|
<h4><a name="rationale" id="rationale">Rationale</a></h4>
|
|
|
|
<p>Specifying the rationale for a function'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't really
|
|
broken as the library matures.</p>
|
|
|
|
<h2 id="web">Web Reference Documentation</h2>
|
|
|
|
<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>
|
|
|
|
<ul>
|
|
<li>Describe the enclosing namespace or use fully scoped
|
|
identifiers.
|
|
<li>Document required headers for each type or function.
|
|
<li>Link to relevant tutorial information.
|
|
<li>Link to related example code.
|
|
<li>Include the library name.
|
|
<li>Include navigation elements to the beginning of the
|
|
documentation.
|
|
</ul>
|
|
|
|
<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>
|
|
|
|
<h2><a name="footnotes" id="footnotes">Footnotes</a></h2>
|
|
|
|
<dl>
|
|
<dt><a class="footnote" id="footnote1" 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.</dt>
|
|
|
|
<dt><a class="footnote" id="footnote2" href="#footnote2-location">(2)</a> Although
|
|
in some cases the code is unambiguously the optimum implementation.</dt>
|
|
|
|
<dt><a class="footnote" id="footnote3" 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.</dt>
|
|
|
|
<dt><a class="footnote" id="footnote4" 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.</dt>
|
|
</dl>
|
|
<hr>
|
|
|
|
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
|
|
"../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
|
|
height="31" width="88"></a></p>
|
|
|
|
<p>Revised
|
|
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
|
|
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
|
|
|
|
<p><i>Copyright © 2001 <a href=
|
|
"mailto:williamkempf@hotmail.com">William E. Kempf</a></i></p>
|
|
|
|
<p><i>Distributed under the Boost Software License, Version 1.0. (See
|
|
accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
|
|
copy at <a href=
|
|
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
|
|
</body>
|
|
</html>
|