mirror of
https://github.com/boostorg/more.git
synced 2024-12-28 23:50:09 +08:00
254 lines
13 KiB
HTML
254 lines
13 KiB
HTML
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<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>
|
|
<dl class="page-index">
|
|
<dt><a href="#elements">Document elements</a></dt>
|
|
<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>
|
|
<dt><a href="#other">Other conventions</a></dt>
|
|
<dl class="page-index">
|
|
<dt><a href="#type-descs">Type descriptions</a></dt>
|
|
</dl>
|
|
</dl>
|
|
<dt><a href="#more">More Information</a></dt>
|
|
<dl class="page-index">
|
|
<dt><a href="#function-semantic-explanations">Function semantic element explanations</a></dt>
|
|
<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>
|
|
</dl>
|
|
<dt><a href="#footnotes">Footnotes</a></dt>
|
|
</dl>
|
|
<h2><a name="introduction">Introduction</a></h2>
|
|
<p>Boost itself does not require any specific documentation structure. The C++
|
|
Standard, however, has very explicit requirements for the description of library
|
|
components (Section 17.3). So for Boost libraries likely to be proposed for
|
|
inclusion in the standard, it is highly desirable to structure documentation
|
|
in a way that meets the requirements of the the standard. Doing so eliminates
|
|
the need to rewrite the documentation for standardization.</p>
|
|
<p>Library developers should remember that for a library to be accepted as part
|
|
of the C++ Standard Library, the proposal must include full wording. The committee
|
|
will not do that work for you.</p>
|
|
<p>Beyond that, the documentation structure required for the standard is an effective
|
|
way to communicate the technical specifications for a library. Although terse,
|
|
it is already familiar to many Boost users, and is far more precise than most
|
|
ad hoc documentation structures.</p>
|
|
<p>The following description is for the structure of documentation required by
|
|
the standard. Boost libraries should also provided additional documentation,
|
|
such as introductory, tutorial, example, and rationale material.</p>
|
|
<h2><a name="standards-conforming">Standards Conforming</a> Documentation</h2>
|
|
<h3><a name="elements">Document elements</a></h3>
|
|
<p>Each document contains the following elements, as applicable<a class="footnote" href="#footnote1">(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">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">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">(2)</a></p>
|
|
<h4><a name="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">(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">elements</a>
|
|
(as appropriate)<a class="footnote" href="#footnote4">(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">References to the C++ Standard library</a></h4>
|
|
<h4><a name="ref-c">References to the C Standard library</a></h4>
|
|
<h3><a name="other">Other conventions</a></h3>
|
|
<p>These conventions are for describing implementation-defined types, and member
|
|
functions.</p>
|
|
<h4><a name="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">More Information</a></h2>
|
|
<h3><a name="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">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,
|
|
<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">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">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">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.
|
|
<h4><a name="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:
|
|
<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">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">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><a name="footnotes">Footnotes</a></h2>
|
|
<dl>
|
|
<dt><a class="footnote" name="footnote1">(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" name="footnote2">(2)</a> Although in some cases the
|
|
code is unambiguously the optimum implementation.</dt>
|
|
<dt><a class="footnote" name="footnote3">(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" name="footnote4">(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>Revised
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->29 November, 2003<!--webbot bot="Timestamp" endspan i-checksum="39371" -->
|
|
</p>
|
|
<p><i>© Copyright <a href="mailto:williamkempf@hotmail.com">William E. Kempf</a>
|
|
2001. All Rights Reserved.</i></p>
|
|
</body>
|
|
</html> |