samien
/
boost
mirror of https://github.com/boostorg/boost


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433
							<!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="#footnotes">Footnotes</a></dt>
  </dl>

  <h2><a name="introduction" id="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" id="standards-conforming">Standards
  Conforming</a> Documentation</h2>

  <h3><a name="elements" id="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" 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">(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">(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">(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>&lt;code&gt; ... &lt;/code&gt;</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 &amp;&amp; min &lt;= 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 &amp; x );
</pre>

  <dl class="function-semantics">
    <dt><b>Postcondition:</b> <code>x &gt;= 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 &gt;
    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><a name="footnotes" id="footnotes">Footnotes</a></h2>

  <dl>
    <dt><a class="footnote" name="footnote1" id="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" id="footnote2">(2)</a> Although
    in some cases the code is unambiguously the optimum implementation.</dt>

    <dt><a class="footnote" name="footnote3" id="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" id="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><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "http://www.w3.org/Icons/valid-html401" 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 &copy; 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>