| 1 | <html> |
|---|
| 2 | <head> |
|---|
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|---|
| 4 | <link rel="stylesheet" type="text/css" href="../../boost.css"> |
|---|
| 5 | <title>Writing Documentation for Boost - Documentation Structure</title> |
|---|
| 6 | </head> |
|---|
| 7 | <body link="#0000ff" vlink="#800080"> |
|---|
| 8 | <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= |
|---|
| 9 | "header"> |
|---|
| 10 | <tr> |
|---|
| 11 | <td valign="top" width="300"> |
|---|
| 12 | <h3><a href="index.html"><img height="86" width="277" alt="C++ Boost" src="../../boost.png" border="0"></a></h3> |
|---|
| 13 | </td> |
|---|
| 14 | <td valign="top"> |
|---|
| 15 | <h1 align="center">Writing Documentation for Boost</h1> |
|---|
| 16 | <h2 align="center">Documentation Structure</h2> |
|---|
| 17 | </td> |
|---|
| 18 | </tr> |
|---|
| 19 | </table> |
|---|
| 20 | <hr> |
|---|
| 21 | <dl class="page-index"> |
|---|
| 22 | <dt><a href="#introduction">Introduction</a></dt> |
|---|
| 23 | <dt><a href="#standards-conforming">Standards Conforming Documentation</a></dt> |
|---|
| 24 | <dl class="page-index"> |
|---|
| 25 | <dt><a href="#elements">Document elements</a></dt> |
|---|
| 26 | <dl class="page-index"> |
|---|
| 27 | <dt><a href="#summary">Summary</a></dt> |
|---|
| 28 | <dt><a href="#requirements">Requirements</a></dt> |
|---|
| 29 | <dt><a href="#detailed-specs">Detailed specifications</a></dt> |
|---|
| 30 | <dt><a href="#ref-cpp">References to the Standard C++ library</a></dt> |
|---|
| 31 | <dt><a href="#ref-c">References to the Standard C library</a></dt> |
|---|
| 32 | </dl> |
|---|
| 33 | <dt><a href="#other">Other conventions</a></dt> |
|---|
| 34 | <dl class="page-index"> |
|---|
| 35 | <dt><a href="#type-descs">Type descriptions</a></dt> |
|---|
| 36 | </dl> |
|---|
| 37 | </dl> |
|---|
| 38 | <dt><a href="#more">More Information</a></dt> |
|---|
| 39 | <dl class="page-index"> |
|---|
| 40 | <dt><a href="#function-semantic-explanations">Function semantic element explanations</a></dt> |
|---|
| 41 | <dl class="page-index"> |
|---|
| 42 | <dt><a href="#requires">Requires</a></dt> |
|---|
| 43 | <dt><a href="#effects">Effects</a></dt> |
|---|
| 44 | <dt><a href="#postconditions">Postconditions</a></dt> |
|---|
| 45 | <dt><a href="#returns">Returns</a></dt> |
|---|
| 46 | <dt><a href="#throws">Throws</a></dt> |
|---|
| 47 | <dt><a href="#complexity">Complexity</a></dt> |
|---|
| 48 | <dt><a href="#rationale">Rationale</a></dt> |
|---|
| 49 | </dl> |
|---|
| 50 | </dl> |
|---|
| 51 | <dt><a href="#footnotes">Footnotes</a></dt> |
|---|
| 52 | </dl> |
|---|
| 53 | <h2><a name="introduction">Introduction</a></h2> |
|---|
| 54 | <p>Boost itself does not require any specific documentation structure. The C++ |
|---|
| 55 | Standard, however, has very explicit requirements for the description of library |
|---|
| 56 | components (Section 17.3). So for Boost libraries likely to be proposed for |
|---|
| 57 | inclusion in the standard, it is highly desirable to structure documentation |
|---|
| 58 | in a way that meets the requirements of the the standard. Doing so eliminates |
|---|
| 59 | the need to rewrite the documentation for standardization.</p> |
|---|
| 60 | <p>Library developers should remember that for a library to be accepted as part |
|---|
| 61 | of the C++ Standard Library, the proposal must include full wording. The committee |
|---|
| 62 | will not do that work for you.</p> |
|---|
| 63 | <p>Beyond that, the documentation structure required for the standard is an effective |
|---|
| 64 | way to communicate the technical specifications for a library. Although terse, |
|---|
| 65 | it is already familiar to many Boost users, and is far more precise than most |
|---|
| 66 | ad hoc documentation structures.</p> |
|---|
| 67 | <p>The following description is for the structure of documentation required by |
|---|
| 68 | the standard. Boost libraries should also provided additional documentation, |
|---|
| 69 | such as introductory, tutorial, example, and rationale material.</p> |
|---|
| 70 | <h2><a name="standards-conforming">Standards Conforming</a> Documentation</h2> |
|---|
| 71 | <h3><a name="elements">Document elements</a></h3> |
|---|
| 72 | <p>Each document contains the following elements, as applicable<a class="footnote" href="#footnote1">(1)</a>:</p> |
|---|
| 73 | <ul> |
|---|
| 74 | <li><a href="#summary">Summary</a></li> |
|---|
| 75 | <li><a href="#requirements">Requirements</a></li> |
|---|
| 76 | <li><a href="#detailed-specs">Detailed specifications</a></li> |
|---|
| 77 | <li><a href="#ref-cpp">References to the Standard C++ library</a></li> |
|---|
| 78 | <li><a href="#ref-c">References to the Standard C library</a></li> |
|---|
| 79 | </ul> |
|---|
| 80 | <h4><a name="summary">Summary</a></h4> |
|---|
| 81 | <p>The Summary provides a synopsis of the category, and introduces the first-level |
|---|
| 82 | subclauses. Each subclause also provides a summary, listing the headers specified |
|---|
| 83 | in the subclause and the library entities provided in each header.</p> |
|---|
| 84 | <p>Paragraphs labeled "Note(s):" or "Example(s):" are informative, other paragraphs |
|---|
| 85 | are normative.</p> |
|---|
| 86 | <p>The summary and the detailed specifications are presented in the order:</p> |
|---|
| 87 | <ul> |
|---|
| 88 | <li>Macros</li> |
|---|
| 89 | <li>Values</li> |
|---|
| 90 | <li>Types</li> |
|---|
| 91 | <li>Classes</li> |
|---|
| 92 | <li>Functions</li> |
|---|
| 93 | <li>Objects</li> |
|---|
| 94 | </ul> |
|---|
| 95 | <h4><a name="requirements">Requirements</a></h4> |
|---|
| 96 | <p>The library can be extended by a C++ program. Each clause, as applicable, describes |
|---|
| 97 | the requirements that such extensions must meet. Such extensions are generally |
|---|
| 98 | one of the following:</p> |
|---|
| 99 | <ul> |
|---|
| 100 | <li>Template arguments</li> |
|---|
| 101 | <li>Derived classes</li> |
|---|
| 102 | <li>Containers, iterators, and/or algorithms that meet an interface convention</li> |
|---|
| 103 | </ul> |
|---|
| 104 | <p>Interface convention requirements are stated as generally as possible. Instead |
|---|
| 105 | of stating "<code>class X</code> has to define a member function <code>operator++()</code>," |
|---|
| 106 | the interface requires "for any object <code>x</code> of <code>class X</code>, |
|---|
| 107 | <code>++x</code> is defined." That is, whether the operator is a member is unspecified.</p> |
|---|
| 108 | <p>Requirements are stated in terms of well-defined expressions, which define |
|---|
| 109 | valid terms of the types that satisfy the requirements. For every set of requirements |
|---|
| 110 | there is a table that specifies an initial set of the valid expressions and |
|---|
| 111 | their semantics. Any generic algorithm that uses the requirements is described |
|---|
| 112 | in terms of the valid expressions for its formal type parameters.</p> |
|---|
| 113 | <p>Template argument requirements are sometimes referenced by name.</p> |
|---|
| 114 | <p>In some cases the semantic requirements are presented as C++ code. Such code |
|---|
| 115 | is intended as a specification of equivalance of a construct to another construct, |
|---|
| 116 | not necessarily as the way the construct must be implemented.<a class="footnote" href="#footnote2">(2)</a></p> |
|---|
| 117 | <h4><a name="detailed-specs">Detailed specification</a></h4> |
|---|
| 118 | <p>The detailed specifications each contain the following elements:</p> |
|---|
| 119 | <ul> |
|---|
| 120 | <li>Name and brief description</li> |
|---|
| 121 | <li>Synopsis (class definition or function prototype, as appropriate)</li> |
|---|
| 122 | <li>Restrictions on template arguments, if any</li> |
|---|
| 123 | <li>Description of class invariants</li> |
|---|
| 124 | <li>Description of function semantics</li> |
|---|
| 125 | </ul> |
|---|
| 126 | <p>Descriptions of class member functions follow the order (as appropriate)<a class="footnote" href="#footnote3">(3)</a>:</p> |
|---|
| 127 | <ul> |
|---|
| 128 | <li>Constructor(s) and destructor</li> |
|---|
| 129 | <li>Copying and assignment functions</li> |
|---|
| 130 | <li>Comparison functions</li> |
|---|
| 131 | <li>Modifier functions</li> |
|---|
| 132 | <li>Observer functions</li> |
|---|
| 133 | <li>Operators and other non-member functions</li> |
|---|
| 134 | </ul> |
|---|
| 135 | <p>Descriptions of function semantics contain the following <a name="function-elements">elements</a> |
|---|
| 136 | (as appropriate)<a class="footnote" href="#footnote4">(4):</a></p> |
|---|
| 137 | <dl class="function-semantics"> |
|---|
| 138 | <dt><b><a href="#requires">Requires:</a></b> the preconditions for calling the |
|---|
| 139 | function</dt> |
|---|
| 140 | <dt><b><a href="#effects">Effects:</a></b> the actions performed by the function</dt> |
|---|
| 141 | <dt><b><a href="#postconditions">Postconditions:</a></b> the observable results |
|---|
| 142 | established by the function</dt> |
|---|
| 143 | <dt><b><a href="#returns">Returns:</a></b> a description of the value(s) returned |
|---|
| 144 | by the function</dt> |
|---|
| 145 | <dt><b><a href="#throws">Throws:</a></b> any exceptions thrown by the function, |
|---|
| 146 | and the conditions that would cause the exception</dt> |
|---|
| 147 | <dt><b><a href="#complexity">Complexity:</a></b> the time and/or space complexity |
|---|
| 148 | of the function</dt> |
|---|
| 149 | <dt><b><a href="#rationale">Rationale:</a></b> the rationale for the function's design |
|---|
| 150 | or existence</dt> |
|---|
| 151 | </dl> |
|---|
| 152 | <p>Complexity requirements specified in the library clauses are upper bounds, |
|---|
| 153 | and implementations that provide better complexity guarantees satisfy the requirements.</p> |
|---|
| 154 | <h4><a name="ref-cpp">References to the C++ Standard library</a></h4> |
|---|
| 155 | <h4><a name="ref-c">References to the C Standard library</a></h4> |
|---|
| 156 | <h3><a name="other">Other conventions</a></h3> |
|---|
| 157 | <p>These conventions are for describing implementation-defined types, and member |
|---|
| 158 | functions.</p> |
|---|
| 159 | <h4><a name="type-descs">Type descriptions</a></h4> |
|---|
| 160 | <p>The Requirements subclauses may describe names that are used to specify constraints |
|---|
| 161 | on template arguments.</p> |
|---|
| 162 | <h2><a name="more">More Information</a></h2> |
|---|
| 163 | <h3><a name="function-semantic-explanations">Function semantic element explanations</a></h3> |
|---|
| 164 | <p>The function semantic element description <a href="#function-elements">above</a> |
|---|
| 165 | is taken directly from the C++ standard, and is quite terse. Here is a more |
|---|
| 166 | detailed explanation of each of the elements.</p> |
|---|
| 167 | <p>Note the use of the <code><code> ... </code></code> font tag to |
|---|
| 168 | distinguish actual C++ usage from English prose.</p> |
|---|
| 169 | <h4><a name="requires">Requires</a></h4> |
|---|
| 170 | <p>Preconditions for calling the function, typically expressed as predicates. |
|---|
| 171 | The most common preconditions are requirements on the value of arguments, often |
|---|
| 172 | in the form of C++ expressions. For example, |
|---|
| 173 | <pre> |
|---|
| 174 | <code>void limit( int * p, int min, int max );</code> |
|---|
| 175 | </pre> |
|---|
| 176 | <dl class="function-semantics"> |
|---|
| 177 | <dt><b>Requires:</b> <code>p != 0 && min <= max</code></dt> |
|---|
| 178 | </dl> |
|---|
| 179 | <p>Requirements already enforced by the C++ language rules (such as the type of |
|---|
| 180 | arguments) are not repeated in Requires paragraphs.</p> |
|---|
| 181 | <h4><a name="effects">Effects</a></h4> |
|---|
| 182 | <p>The actions performed by the function, described either in prose or in C++. |
|---|
| 183 | A description in prose is often less limiting on implementors, but is often |
|---|
| 184 | less precise than C++ code.</p> |
|---|
| 185 | <p>If an effect is specified in one of the other elements, particularly <i>postconditions</i>, |
|---|
| 186 | <i>returns</i>, or <i>throws</i>, it is not also described in the <i>effects</i> |
|---|
| 187 | paragraph. Having only a single description ensures that there is one and only |
|---|
| 188 | one specification, and thus eliminates the risk of divergence.</p> |
|---|
| 189 | <h4><a name="postconditions">Postconditions</a></h4> |
|---|
| 190 | <p>The observable results of the function, such as the value of variables. Postconditions |
|---|
| 191 | are often expressed as predicates that are true after the function completes, |
|---|
| 192 | in the form of C++ expressions. For example:</p> |
|---|
| 193 | <pre> |
|---|
| 194 | void make_zero_if_negative( int & x ); |
|---|
| 195 | </pre> |
|---|
| 196 | <dl class="function-semantics"> |
|---|
| 197 | <dt><b>Postcondition:</b> <code>x >= 0</code></dt> |
|---|
| 198 | </dl> |
|---|
| 199 | <h4><a name="returns">Returns</a></h4> |
|---|
| 200 | <p>The value returned by the function, usually in the form of a C++ expression. |
|---|
| 201 | For example:</p> |
|---|
| 202 | <pre>int sum( int x, int y ); |
|---|
| 203 | </pre> |
|---|
| 204 | <dl class="function-semantics"> |
|---|
| 205 | <dt><b>Returns:</b> <code>x + y</code></dt> |
|---|
| 206 | </dl> |
|---|
| 207 | <p>Only specify the return value; the type is already dictated by C++ language |
|---|
| 208 | rules. |
|---|
| 209 | <h4><a name="throws">Throws</a></h4> |
|---|
| 210 | <p>Specify both the type of exception thrown, and the condition that causes the |
|---|
| 211 | exception to be thrown. For example, the <code>std::basic_string</code> class |
|---|
| 212 | specifies: |
|---|
| 213 | <pre> |
|---|
| 214 | void resize(size_type n, charT c); |
|---|
| 215 | </pre> |
|---|
| 216 | <dl class="function-semantics"> |
|---|
| 217 | <dt><b>Throws:</b> <code> length_error</code> if <code>n > max_size()</code>.</dt> |
|---|
| 218 | </dl> |
|---|
| 219 | <h4><a name="complexity">Complexity</a></h4> |
|---|
| 220 | <p>Specifying the time and/or space complexity of a function is often not desirable |
|---|
| 221 | because it over-constrains implementors and is hard to specify correctly. Complexity |
|---|
| 222 | is thus often best left as a quality of implementation issue.</p> |
|---|
| 223 | <p>A library component, however, can become effectively non-portable if there |
|---|
| 224 | is wide variation in performance between conforming implementations. Containers |
|---|
| 225 | are a prime example. In these cases it becomes worthwhile to specify complexity.</p> |
|---|
| 226 | <p>Complexity is often specified in generalized <a href="http://hissa.nist.gov/dads/HTML/bigOnotation.html"> |
|---|
| 227 | "Big-O" notation</a>.</p> |
|---|
| 228 | <h4><a name="rationale">Rationale</a></h4> |
|---|
| 229 | <p>Specifying the rationale for a function's design or existence can often give users |
|---|
| 230 | a lot of insight into why a library is designed the way it is. More importantly, it |
|---|
| 231 | can help prevent "fixing" something that wasn't really broken as the library matures.</p> |
|---|
| 232 | <h2><a name="footnotes">Footnotes</a></h2> |
|---|
| 233 | <dl> |
|---|
| 234 | <dt><a class="footnote" name="footnote1">(1)</a> |
|---|
| 235 | To save space, items that do not apply to a clause are omitted. For example, |
|---|
| 236 | if a clause does not specify any requirements, there will be no "Requirements" |
|---|
| 237 | subclause.</dt> |
|---|
| 238 | <dt><a class="footnote" name="footnote2">(2)</a> Although in some cases the |
|---|
| 239 | code is unambiguously the optimum implementation.</dt> |
|---|
| 240 | <dt><a class="footnote" name="footnote3">(3)</a> To save space, items that do |
|---|
| 241 | not apply to a class are omitted. For example, if a class does not specify |
|---|
| 242 | any comparison functions, there will be no "Comparison functions" subclause.</dt> |
|---|
| 243 | <dt><a class="footnote" name="footnote4">(4)</a> To save space, items that do |
|---|
| 244 | not apply to a function are omitted. For example, if a function does not specify |
|---|
| 245 | any precondition, there will be no "Requires" paragraph.</dt> |
|---|
| 246 | </dl> |
|---|
| 247 | <hr> |
|---|
| 248 | <p>Revised |
|---|
| 249 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->29 November, 2003<!--webbot bot="Timestamp" endspan i-checksum="39371" --> |
|---|
| 250 | </p> |
|---|
| 251 | <p><i>© Copyright <a href="mailto:williamkempf@hotmail.com">William E. Kempf</a> |
|---|
| 252 | 2001. All Rights Reserved.</i></p> |
|---|
| 253 | </body> |
|---|
| 254 | </html> |
|---|
