| <!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> |