mirror of
https://github.com/boostorg/more.git
synced 2025-01-14 02:20:08 +08:00
d3a33c2e2a
Merged revisions 53551,53611-53613,53637 via svnmerge from https://svn.boost.org/svn/boost/trunk ........ r53551 | danieljames | 2009-06-01 20:18:00 +0100 (Mon, 01 Jun 2009) | 1 line Extra guidelines for writing documentation for the web. ........ r53611 | danieljames | 2009-06-03 23:48:11 +0100 (Wed, 03 Jun 2009) | 1 line New introduction and web reference guidelines, by Robert Stewart. ........ r53612 | danieljames | 2009-06-03 23:48:22 +0100 (Wed, 03 Jun 2009) | 2 lines Use the second paragraph of Robert's introduction as an introduction to the standard guidelines section. Reintroduce the reference to the standard and link to the 'more information' section. ........ r53613 | danieljames | 2009-06-03 23:48:35 +0100 (Wed, 03 Jun 2009) | 1 line Link footnotes back to their location in the document. ........ r53637 | danieljames | 2009-06-04 17:43:30 +0100 (Thu, 04 Jun 2009) | 1 line Writing docs tweaks from Robert Stewart. ........ [SVN r53683]
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=us-ascii">
|
|
<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>
|