| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
|---|
| 2 | |
|---|
| 3 | <html> |
|---|
| 4 | <head> |
|---|
| 5 | <meta http-equiv="Content-Language" content="en-us"> |
|---|
| 6 | <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> |
|---|
| 7 | <link rel="stylesheet" type="text/css" href="../../boost.css"> |
|---|
| 8 | |
|---|
| 9 | <title>Writing Documentation for Boost - Documentation Structure</title> |
|---|
| 10 | </head> |
|---|
| 11 | |
|---|
| 12 | <body link="#0000FF" vlink="#800080"> |
|---|
| 13 | <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= |
|---|
| 14 | "header"> |
|---|
| 15 | <tr> |
|---|
| 16 | <td valign="top" width="300"> |
|---|
| 17 | <h3><a href="index.html"><img height="86" width="277" alt="C++ Boost" |
|---|
| 18 | src="../../boost.png" border="0"></a></h3> |
|---|
| 19 | </td> |
|---|
| 20 | |
|---|
| 21 | <td valign="top"> |
|---|
| 22 | <h1 align="center">Writing Documentation for Boost</h1> |
|---|
| 23 | |
|---|
| 24 | <h2 align="center">Documentation Structure</h2> |
|---|
| 25 | </td> |
|---|
| 26 | </tr> |
|---|
| 27 | </table> |
|---|
| 28 | <hr> |
|---|
| 29 | |
|---|
| 30 | <dl class="page-index"> |
|---|
| 31 | <dt><a href="#introduction">Introduction</a></dt> |
|---|
| 32 | |
|---|
| 33 | <dt><a href="#standards-conforming">Standards Conforming |
|---|
| 34 | Documentation</a></dt> |
|---|
| 35 | |
|---|
| 36 | <dd> |
|---|
| 37 | <dl class="page-index"> |
|---|
| 38 | <dt><a href="#elements">Document elements</a></dt> |
|---|
| 39 | |
|---|
| 40 | <dd> |
|---|
| 41 | <dl class="page-index"> |
|---|
| 42 | <dt><a href="#summary">Summary</a></dt> |
|---|
| 43 | |
|---|
| 44 | <dt><a href="#requirements">Requirements</a></dt> |
|---|
| 45 | |
|---|
| 46 | <dt><a href="#detailed-specs">Detailed specifications</a></dt> |
|---|
| 47 | |
|---|
| 48 | <dt><a href="#ref-cpp">References to the Standard C++ |
|---|
| 49 | library</a></dt> |
|---|
| 50 | |
|---|
| 51 | <dt><a href="#ref-c">References to the Standard C |
|---|
| 52 | library</a></dt> |
|---|
| 53 | </dl> |
|---|
| 54 | </dd> |
|---|
| 55 | |
|---|
| 56 | <dt><a href="#other">Other conventions</a></dt> |
|---|
| 57 | |
|---|
| 58 | <dd> |
|---|
| 59 | <dl class="page-index"> |
|---|
| 60 | <dt><a href="#type-descs">Type descriptions</a></dt> |
|---|
| 61 | </dl> |
|---|
| 62 | </dd> |
|---|
| 63 | </dl> |
|---|
| 64 | </dd> |
|---|
| 65 | |
|---|
| 66 | <dt><a href="#more">More Information</a></dt> |
|---|
| 67 | |
|---|
| 68 | <dd> |
|---|
| 69 | <dl class="page-index"> |
|---|
| 70 | <dt><a href="#function-semantic-explanations">Function semantic |
|---|
| 71 | element explanations</a></dt> |
|---|
| 72 | |
|---|
| 73 | <dd> |
|---|
| 74 | <dl class="page-index"> |
|---|
| 75 | <dt><a href="#requires">Requires</a></dt> |
|---|
| 76 | |
|---|
| 77 | <dt><a href="#effects">Effects</a></dt> |
|---|
| 78 | |
|---|
| 79 | <dt><a href="#postconditions">Postconditions</a></dt> |
|---|
| 80 | |
|---|
| 81 | <dt><a href="#returns">Returns</a></dt> |
|---|
| 82 | |
|---|
| 83 | <dt><a href="#throws">Throws</a></dt> |
|---|
| 84 | |
|---|
| 85 | <dt><a href="#complexity">Complexity</a></dt> |
|---|
| 86 | |
|---|
| 87 | <dt><a href="#rationale">Rationale</a></dt> |
|---|
| 88 | </dl> |
|---|
| 89 | </dd> |
|---|
| 90 | </dl> |
|---|
| 91 | </dd> |
|---|
| 92 | |
|---|
| 93 | <dt><a href="#footnotes">Footnotes</a></dt> |
|---|
| 94 | </dl> |
|---|
| 95 | |
|---|
| 96 | <h2><a name="introduction" id="introduction">Introduction</a></h2> |
|---|
| 97 | |
|---|
| 98 | <p>Boost itself does not require any specific documentation structure. The |
|---|
| 99 | C++ Standard, however, has very explicit requirements for the description |
|---|
| 100 | of library components (Section 17.3). So for Boost libraries likely to be |
|---|
| 101 | proposed for inclusion in the standard, it is highly desirable to structure |
|---|
| 102 | documentation in a way that meets the requirements of the the standard. |
|---|
| 103 | Doing so eliminates the need to rewrite the documentation for |
|---|
| 104 | standardization.</p> |
|---|
| 105 | |
|---|
| 106 | <p>Library developers should remember that for a library to be accepted as |
|---|
| 107 | part of the C++ Standard Library, the proposal must include full wording. |
|---|
| 108 | The committee will not do that work for you.</p> |
|---|
| 109 | |
|---|
| 110 | <p>Beyond that, the documentation structure required for the standard is an |
|---|
| 111 | effective way to communicate the technical specifications for a library. |
|---|
| 112 | Although terse, it is already familiar to many Boost users, and is far more |
|---|
| 113 | precise than most ad hoc documentation structures.</p> |
|---|
| 114 | |
|---|
| 115 | <p>The following description is for the structure of documentation required |
|---|
| 116 | by the standard. Boost libraries should also provided additional |
|---|
| 117 | documentation, such as introductory, tutorial, example, and rationale |
|---|
| 118 | material.</p> |
|---|
| 119 | |
|---|
| 120 | <h2><a name="standards-conforming" id="standards-conforming">Standards |
|---|
| 121 | Conforming</a> Documentation</h2> |
|---|
| 122 | |
|---|
| 123 | <h3><a name="elements" id="elements">Document elements</a></h3> |
|---|
| 124 | |
|---|
| 125 | <p>Each document contains the following elements, as applicable<a class= |
|---|
| 126 | "footnote" href="#footnote1">(1)</a>:</p> |
|---|
| 127 | |
|---|
| 128 | <ul> |
|---|
| 129 | <li><a href="#summary">Summary</a></li> |
|---|
| 130 | |
|---|
| 131 | <li><a href="#requirements">Requirements</a></li> |
|---|
| 132 | |
|---|
| 133 | <li><a href="#detailed-specs">Detailed specifications</a></li> |
|---|
| 134 | |
|---|
| 135 | <li><a href="#ref-cpp">References to the Standard C++ library</a></li> |
|---|
| 136 | |
|---|
| 137 | <li><a href="#ref-c">References to the Standard C library</a></li> |
|---|
| 138 | </ul> |
|---|
| 139 | |
|---|
| 140 | <h4><a name="summary" id="summary">Summary</a></h4> |
|---|
| 141 | |
|---|
| 142 | <p>The Summary provides a synopsis of the category, and introduces the |
|---|
| 143 | first-level subclauses. Each subclause also provides a summary, listing the |
|---|
| 144 | headers specified in the subclause and the library entities provided in |
|---|
| 145 | each header.</p> |
|---|
| 146 | |
|---|
| 147 | <p>Paragraphs labeled "Note(s):" or "Example(s):" are informative, other |
|---|
| 148 | paragraphs are normative.</p> |
|---|
| 149 | |
|---|
| 150 | <p>The summary and the detailed specifications are presented in the |
|---|
| 151 | order:</p> |
|---|
| 152 | |
|---|
| 153 | <ul> |
|---|
| 154 | <li>Macros</li> |
|---|
| 155 | |
|---|
| 156 | <li>Values</li> |
|---|
| 157 | |
|---|
| 158 | <li>Types</li> |
|---|
| 159 | |
|---|
| 160 | <li>Classes</li> |
|---|
| 161 | |
|---|
| 162 | <li>Functions</li> |
|---|
| 163 | |
|---|
| 164 | <li>Objects</li> |
|---|
| 165 | </ul> |
|---|
| 166 | |
|---|
| 167 | <h4><a name="requirements" id="requirements">Requirements</a></h4> |
|---|
| 168 | |
|---|
| 169 | <p>The library can be extended by a C++ program. Each clause, as |
|---|
| 170 | applicable, describes the requirements that such extensions must meet. Such |
|---|
| 171 | extensions are generally one of the following:</p> |
|---|
| 172 | |
|---|
| 173 | <ul> |
|---|
| 174 | <li>Template arguments</li> |
|---|
| 175 | |
|---|
| 176 | <li>Derived classes</li> |
|---|
| 177 | |
|---|
| 178 | <li>Containers, iterators, and/or algorithms that meet an interface |
|---|
| 179 | convention</li> |
|---|
| 180 | </ul> |
|---|
| 181 | |
|---|
| 182 | <p>Interface convention requirements are stated as generally as possible. |
|---|
| 183 | Instead of stating "<code>class X</code> has to define a member function |
|---|
| 184 | <code>operator++()</code>," the interface requires "for any object |
|---|
| 185 | <code>x</code> of <code>class X</code>, <code>++x</code> is defined." That |
|---|
| 186 | is, whether the operator is a member is unspecified.</p> |
|---|
| 187 | |
|---|
| 188 | <p>Requirements are stated in terms of well-defined expressions, which |
|---|
| 189 | define valid terms of the types that satisfy the requirements. For every |
|---|
| 190 | set of requirements there is a table that specifies an initial set of the |
|---|
| 191 | valid expressions and their semantics. Any generic algorithm that uses the |
|---|
| 192 | requirements is described in terms of the valid expressions for its formal |
|---|
| 193 | type parameters.</p> |
|---|
| 194 | |
|---|
| 195 | <p>Template argument requirements are sometimes referenced by name.</p> |
|---|
| 196 | |
|---|
| 197 | <p>In some cases the semantic requirements are presented as C++ code. Such |
|---|
| 198 | code is intended as a specification of equivalance of a construct to |
|---|
| 199 | another construct, not necessarily as the way the construct must be |
|---|
| 200 | implemented.<a class="footnote" href="#footnote2">(2)</a></p> |
|---|
| 201 | |
|---|
| 202 | <h4><a name="detailed-specs" id="detailed-specs">Detailed |
|---|
| 203 | specification</a></h4> |
|---|
| 204 | |
|---|
| 205 | <p>The detailed specifications each contain the following elements:</p> |
|---|
| 206 | |
|---|
| 207 | <ul> |
|---|
| 208 | <li>Name and brief description</li> |
|---|
| 209 | |
|---|
| 210 | <li>Synopsis (class definition or function prototype, as |
|---|
| 211 | appropriate)</li> |
|---|
| 212 | |
|---|
| 213 | <li>Restrictions on template arguments, if any</li> |
|---|
| 214 | |
|---|
| 215 | <li>Description of class invariants</li> |
|---|
| 216 | |
|---|
| 217 | <li>Description of function semantics</li> |
|---|
| 218 | </ul> |
|---|
| 219 | |
|---|
| 220 | <p>Descriptions of class member functions follow the order (as |
|---|
| 221 | appropriate)<a class="footnote" href="#footnote3">(3)</a>:</p> |
|---|
| 222 | |
|---|
| 223 | <ul> |
|---|
| 224 | <li>Constructor(s) and destructor</li> |
|---|
| 225 | |
|---|
| 226 | <li>Copying and assignment functions</li> |
|---|
| 227 | |
|---|
| 228 | <li>Comparison functions</li> |
|---|
| 229 | |
|---|
| 230 | <li>Modifier functions</li> |
|---|
| 231 | |
|---|
| 232 | <li>Observer functions</li> |
|---|
| 233 | |
|---|
| 234 | <li>Operators and other non-member functions</li> |
|---|
| 235 | </ul> |
|---|
| 236 | |
|---|
| 237 | <p>Descriptions of function semantics contain the following <a name= |
|---|
| 238 | "function-elements" id="function-elements">elements</a> (as |
|---|
| 239 | appropriate)<a class="footnote" href="#footnote4">(4):</a></p> |
|---|
| 240 | |
|---|
| 241 | <dl class="function-semantics"> |
|---|
| 242 | <dt><b><a href="#requires">Requires:</a></b> the preconditions for |
|---|
| 243 | calling the function</dt> |
|---|
| 244 | |
|---|
| 245 | <dt><b><a href="#effects">Effects:</a></b> the actions performed by the |
|---|
| 246 | function</dt> |
|---|
| 247 | |
|---|
| 248 | <dt><b><a href="#postconditions">Postconditions:</a></b> the observable |
|---|
| 249 | results established by the function</dt> |
|---|
| 250 | |
|---|
| 251 | <dt><b><a href="#returns">Returns:</a></b> a description of the value(s) |
|---|
| 252 | returned by the function</dt> |
|---|
| 253 | |
|---|
| 254 | <dt><b><a href="#throws">Throws:</a></b> any exceptions thrown by the |
|---|
| 255 | function, and the conditions that would cause the exception</dt> |
|---|
| 256 | |
|---|
| 257 | <dt><b><a href="#complexity">Complexity:</a></b> the time and/or space |
|---|
| 258 | complexity of the function</dt> |
|---|
| 259 | |
|---|
| 260 | <dt><b><a href="#rationale">Rationale:</a></b> the rationale for the |
|---|
| 261 | function's design or existence</dt> |
|---|
| 262 | </dl> |
|---|
| 263 | |
|---|
| 264 | <p>Complexity requirements specified in the library clauses are upper |
|---|
| 265 | bounds, and implementations that provide better complexity guarantees |
|---|
| 266 | satisfy the requirements.</p> |
|---|
| 267 | |
|---|
| 268 | <h4><a name="ref-cpp" id="ref-cpp">References to the C++ Standard |
|---|
| 269 | library</a></h4> |
|---|
| 270 | |
|---|
| 271 | <h4><a name="ref-c" id="ref-c">References to the C Standard |
|---|
| 272 | library</a></h4> |
|---|
| 273 | |
|---|
| 274 | <h3><a name="other" id="other">Other conventions</a></h3> |
|---|
| 275 | |
|---|
| 276 | <p>These conventions are for describing implementation-defined types, and |
|---|
| 277 | member functions.</p> |
|---|
| 278 | |
|---|
| 279 | <h4><a name="type-descs" id="type-descs">Type descriptions</a></h4> |
|---|
| 280 | |
|---|
| 281 | <p>The Requirements subclauses may describe names that are used to specify |
|---|
| 282 | constraints on template arguments.</p> |
|---|
| 283 | |
|---|
| 284 | <h2><a name="more" id="more">More Information</a></h2> |
|---|
| 285 | |
|---|
| 286 | <h3><a name="function-semantic-explanations" id= |
|---|
| 287 | "function-semantic-explanations">Function semantic element |
|---|
| 288 | explanations</a></h3> |
|---|
| 289 | |
|---|
| 290 | <p>The function semantic element description <a href= |
|---|
| 291 | "#function-elements">above</a> is taken directly from the C++ standard, and |
|---|
| 292 | is quite terse. Here is a more detailed explanation of each of the |
|---|
| 293 | elements.</p> |
|---|
| 294 | |
|---|
| 295 | <p>Note the use of the <code><code> ... </code></code> font tag |
|---|
| 296 | to distinguish actual C++ usage from English prose.</p> |
|---|
| 297 | |
|---|
| 298 | <h4><a name="requires" id="requires">Requires</a></h4> |
|---|
| 299 | |
|---|
| 300 | <p>Preconditions for calling the function, typically expressed as |
|---|
| 301 | predicates. The most common preconditions are requirements on the value of |
|---|
| 302 | arguments, often in the form of C++ expressions. For example,</p> |
|---|
| 303 | <pre> |
|---|
| 304 | |
|---|
| 305 | <code>void limit( int * p, int min, int max );</code> |
|---|
| 306 | </pre> |
|---|
| 307 | |
|---|
| 308 | <dl class="function-semantics"> |
|---|
| 309 | <dt><b>Requires:</b> <code>p != 0 && min <= max</code></dt> |
|---|
| 310 | </dl> |
|---|
| 311 | |
|---|
| 312 | <p>Requirements already enforced by the C++ language rules (such as the |
|---|
| 313 | type of arguments) are not repeated in Requires paragraphs.</p> |
|---|
| 314 | |
|---|
| 315 | <h4><a name="effects" id="effects">Effects</a></h4> |
|---|
| 316 | |
|---|
| 317 | <p>The actions performed by the function, described either in prose or in |
|---|
| 318 | C++. A description in prose is often less limiting on implementors, but is |
|---|
| 319 | often less precise than C++ code.</p> |
|---|
| 320 | |
|---|
| 321 | <p>If an effect is specified in one of the other elements, particularly |
|---|
| 322 | <i>postconditions</i>, <i>returns</i>, or <i>throws</i>, it is not also |
|---|
| 323 | described in the <i>effects</i> paragraph. Having only a single description |
|---|
| 324 | ensures that there is one and only one specification, and thus eliminates |
|---|
| 325 | the risk of divergence.</p> |
|---|
| 326 | |
|---|
| 327 | <h4><a name="postconditions" id="postconditions">Postconditions</a></h4> |
|---|
| 328 | |
|---|
| 329 | <p>The observable results of the function, such as the value of variables. |
|---|
| 330 | Postconditions are often expressed as predicates that are true after the |
|---|
| 331 | function completes, in the form of C++ expressions. For example:</p> |
|---|
| 332 | <pre> |
|---|
| 333 | |
|---|
| 334 | void make_zero_if_negative( int & x ); |
|---|
| 335 | </pre> |
|---|
| 336 | |
|---|
| 337 | <dl class="function-semantics"> |
|---|
| 338 | <dt><b>Postcondition:</b> <code>x >= 0</code></dt> |
|---|
| 339 | </dl> |
|---|
| 340 | |
|---|
| 341 | <h4><a name="returns" id="returns">Returns</a></h4> |
|---|
| 342 | |
|---|
| 343 | <p>The value returned by the function, usually in the form of a C++ |
|---|
| 344 | expression. For example:</p> |
|---|
| 345 | <pre> |
|---|
| 346 | int sum( int x, int y ); |
|---|
| 347 | </pre> |
|---|
| 348 | |
|---|
| 349 | <dl class="function-semantics"> |
|---|
| 350 | <dt><b>Returns:</b> <code>x + y</code></dt> |
|---|
| 351 | </dl> |
|---|
| 352 | |
|---|
| 353 | <p>Only specify the return value; the type is already dictated by C++ |
|---|
| 354 | language rules.</p> |
|---|
| 355 | |
|---|
| 356 | <h4><a name="throws" id="throws">Throws</a></h4> |
|---|
| 357 | |
|---|
| 358 | <p>Specify both the type of exception thrown, and the condition that causes |
|---|
| 359 | the exception to be thrown. For example, the <code>std::basic_string</code> |
|---|
| 360 | class specifies:</p> |
|---|
| 361 | <pre> |
|---|
| 362 | |
|---|
| 363 | void resize(size_type n, charT c); |
|---|
| 364 | </pre> |
|---|
| 365 | |
|---|
| 366 | <dl class="function-semantics"> |
|---|
| 367 | <dt><b>Throws:</b> <code>length_error</code> if <code>n > |
|---|
| 368 | max_size()</code>.</dt> |
|---|
| 369 | </dl> |
|---|
| 370 | |
|---|
| 371 | <h4><a name="complexity" id="complexity">Complexity</a></h4> |
|---|
| 372 | |
|---|
| 373 | <p>Specifying the time and/or space complexity of a function is often not |
|---|
| 374 | desirable because it over-constrains implementors and is hard to specify |
|---|
| 375 | correctly. Complexity is thus often best left as a quality of |
|---|
| 376 | implementation issue.</p> |
|---|
| 377 | |
|---|
| 378 | <p>A library component, however, can become effectively non-portable if |
|---|
| 379 | there is wide variation in performance between conforming implementations. |
|---|
| 380 | Containers are a prime example. In these cases it becomes worthwhile to |
|---|
| 381 | specify complexity.</p> |
|---|
| 382 | |
|---|
| 383 | <p>Complexity is often specified in generalized <a href= |
|---|
| 384 | "http://hissa.nist.gov/dads/HTML/bigOnotation.html">"Big-O" |
|---|
| 385 | notation</a>.</p> |
|---|
| 386 | |
|---|
| 387 | <h4><a name="rationale" id="rationale">Rationale</a></h4> |
|---|
| 388 | |
|---|
| 389 | <p>Specifying the rationale for a function's design or existence can often |
|---|
| 390 | give users a lot of insight into why a library is designed the way it is. |
|---|
| 391 | More importantly, it can help prevent "fixing" something that wasn't really |
|---|
| 392 | broken as the library matures.</p> |
|---|
| 393 | |
|---|
| 394 | <h2><a name="footnotes" id="footnotes">Footnotes</a></h2> |
|---|
| 395 | |
|---|
| 396 | <dl> |
|---|
| 397 | <dt><a class="footnote" name="footnote1" id="footnote1">(1)</a> To save |
|---|
| 398 | space, items that do not apply to a clause are omitted. For example, if a |
|---|
| 399 | clause does not specify any requirements, there will be no "Requirements" |
|---|
| 400 | subclause.</dt> |
|---|
| 401 | |
|---|
| 402 | <dt><a class="footnote" name="footnote2" id="footnote2">(2)</a> Although |
|---|
| 403 | in some cases the code is unambiguously the optimum implementation.</dt> |
|---|
| 404 | |
|---|
| 405 | <dt><a class="footnote" name="footnote3" id="footnote3">(3)</a> To save |
|---|
| 406 | space, items that do not apply to a class are omitted. For example, if a |
|---|
| 407 | class does not specify any comparison functions, there will be no |
|---|
| 408 | "Comparison functions" subclause.</dt> |
|---|
| 409 | |
|---|
| 410 | <dt><a class="footnote" name="footnote4" id="footnote4">(4)</a> To save |
|---|
| 411 | space, items that do not apply to a function are omitted. For example, if |
|---|
| 412 | a function does not specify any precondition, there will be no "Requires" |
|---|
| 413 | paragraph.</dt> |
|---|
| 414 | </dl> |
|---|
| 415 | <hr> |
|---|
| 416 | |
|---|
| 417 | <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src= |
|---|
| 418 | "http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional" |
|---|
| 419 | height="31" width="88"></a></p> |
|---|
| 420 | |
|---|
| 421 | <p>Revised |
|---|
| 422 | <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04 |
|---|
| 423 | December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p> |
|---|
| 424 | |
|---|
| 425 | <p><i>Copyright © 2001 <a href= |
|---|
| 426 | "mailto:williamkempf@hotmail.com">William E. Kempf</a></i></p> |
|---|
| 427 | |
|---|
| 428 | <p><i>Distributed under the Boost Software License, Version 1.0. (See |
|---|
| 429 | accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or |
|---|
| 430 | copy at <a href= |
|---|
| 431 | "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p> |
|---|
| 432 | </body> |
|---|
| 433 | </html> |
|---|
