1 <!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
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">
9 <title>Writing Documentation for Boost - Documentation Structure
</title>
12 <body link=
"#0000FF" vlink=
"#800080">
13 <table border=
"0" cellpadding=
"7" cellspacing=
"0" width=
"100%" summary=
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>
22 <h1 align=
"center">Writing Documentation for Boost
</h1>
24 <h2 align=
"center">Documentation Structure
</h2>
30 <dl class=
"page-index">
31 <dt><a href=
"#introduction">Introduction
</a></dt>
33 <dt><a href=
"#standards-conforming">Standards Conforming
34 Documentation
</a></dt>
37 <dl class=
"page-index">
38 <dt><a href=
"#elements">Document elements
</a></dt>
41 <dl class=
"page-index">
42 <dt><a href=
"#summary">Summary
</a></dt>
44 <dt><a href=
"#requirements">Requirements
</a></dt>
46 <dt><a href=
"#detailed-specs">Detailed specifications
</a></dt>
48 <dt><a href=
"#ref-cpp">References to the Standard C++
51 <dt><a href=
"#ref-c">References to the Standard C
56 <dt><a href=
"#other">Other conventions
</a></dt>
59 <dl class=
"page-index">
60 <dt><a href=
"#type-descs">Type descriptions
</a></dt>
66 <dt><a href=
"#more">More Information
</a></dt>
69 <dl class=
"page-index">
70 <dt><a href=
"#function-semantic-explanations">Function semantic
71 element explanations
</a></dt>
74 <dl class=
"page-index">
75 <dt><a href=
"#requires">Requires
</a></dt>
77 <dt><a href=
"#effects">Effects
</a></dt>
79 <dt><a href=
"#postconditions">Postconditions
</a></dt>
81 <dt><a href=
"#returns">Returns
</a></dt>
83 <dt><a href=
"#throws">Throws
</a></dt>
85 <dt><a href=
"#complexity">Complexity
</a></dt>
87 <dt><a href=
"#rationale">Rationale
</a></dt>
93 <dt><a href=
"#web">Web Reference Documentation
</a></dt>
95 <dt><a href=
"#footnotes">Footnotes
</a></dt>
98 <h2><a name=
"introduction" id=
"introduction">Introduction
</a></h2>
100 <p>Boost does not require any specific documentation structure.
101 However, there are some important considerations that
102 influence content and structure. For example, many Boost
103 libraries wind up being proposed for inclusion in the C++
104 Standard, so writing them initially with text suitable for
105 inclusion in the Standard may be helpful. Also, Boost library
106 documentation is often accessed via the World Wide Web,
107 including via search engines, so context is often important
108 for every page. Finally, Boost libraries should provide
109 additional documentation, such as introductory, tutorial,
110 example, and rationale content. With those things in mind, we
111 suggest the following guidelines for Boost library
114 <h2><a name=
"standards-conforming" id=
"standards-conforming">Standards
115 Conforming
</a> Documentation
</h2>
117 <p>The documentation structure required for the C++ Standard is
118 an effective way to describe the technical specifications for
119 a library. Although terse, that format is familiar to many
120 Boost users and is far more precise than most ad hoc formats.
121 The following description is based upon
§17.3 of the
122 Standard. (Note that while final Standard proposals must
123 include full standardese wording, which the committee will
124 not do for you, that level of detail is not expected of Boost
125 library documentation.)
</p>
127 <h3><a name=
"elements" id=
"elements">Document elements
</a></h3>
129 <p>Each document contains the following elements, as applicable
<a class=
130 "footnote" href=
"#footnote1" id=
"footnote1-location">(
1)
</a>:
</p>
133 <li><a href=
"#summary">Summary
</a></li>
135 <li><a href=
"#requirements">Requirements
</a></li>
137 <li><a href=
"#detailed-specs">Detailed specifications
</a></li>
139 <li><a href=
"#ref-cpp">References to the Standard C++ library
</a></li>
141 <li><a href=
"#ref-c">References to the Standard C library
</a></li>
144 <h4><a name=
"summary" id=
"summary">Summary
</a></h4>
146 <p>The Summary provides a synopsis of the category, and introduces the
147 first-level subclauses. Each subclause also provides a summary, listing the
148 headers specified in the subclause and the library entities provided in
151 <p>Paragraphs labeled
"Note(s):" or
"Example(s):" are informative, other
152 paragraphs are normative.
</p>
154 <p>The summary and the detailed specifications are presented in the
171 <h4><a name=
"requirements" id=
"requirements">Requirements
</a></h4>
173 <p>The library can be extended by a C++ program. Each clause, as
174 applicable, describes the requirements that such extensions must meet. Such
175 extensions are generally one of the following:
</p>
178 <li>Template arguments
</li>
180 <li>Derived classes
</li>
182 <li>Containers, iterators, and/or algorithms that meet an interface
186 <p>Interface convention requirements are stated as generally as possible.
187 Instead of stating
"<code>class X</code> has to define a member function
188 <code>operator++()</code>," the interface requires
"for any object
189 <code>x</code> of <code>class X</code>, <code>++x</code> is defined." That
190 is, whether the operator is a member is unspecified.
</p>
192 <p>Requirements are stated in terms of well-defined expressions, which
193 define valid terms of the types that satisfy the requirements. For every
194 set of requirements there is a table that specifies an initial set of the
195 valid expressions and their semantics. Any generic algorithm that uses the
196 requirements is described in terms of the valid expressions for its formal
199 <p>Template argument requirements are sometimes referenced by name.
</p>
201 <p>In some cases the semantic requirements are presented as C++ code. Such
202 code is intended as a specification of equivalance of a construct to
203 another construct, not necessarily as the way the construct must be
204 implemented.
<a class=
"footnote" href=
"#footnote2" id=
"footnote2-location">(
2)
</a></p>
206 <h4><a name=
"detailed-specs" id=
"detailed-specs">Detailed
207 specification
</a></h4>
209 <p>The detailed specifications each contain the following elements:
</p>
212 <li>Name and brief description
</li>
214 <li>Synopsis (class definition or function prototype, as
217 <li>Restrictions on template arguments, if any
</li>
219 <li>Description of class invariants
</li>
221 <li>Description of function semantics
</li>
224 <p>Descriptions of class member functions follow the order (as
225 appropriate)
<a class=
"footnote" href=
"#footnote3" id=
"footnote3-location">(
3)
</a>:
</p>
228 <li>Constructor(s) and destructor
</li>
230 <li>Copying and assignment functions
</li>
232 <li>Comparison functions
</li>
234 <li>Modifier functions
</li>
236 <li>Observer functions
</li>
238 <li>Operators and other non-member functions
</li>
241 <p>Descriptions of function semantics contain the following
<a name=
242 "function-elements" id=
"function-elements">elements
</a> (as
243 appropriate)
<a class=
"footnote" href=
"#footnote4" id=
"footnote4-location">(
4):
</a></p>
245 <dl class=
"function-semantics">
246 <dt><b><a href=
"#requires">Requires:
</a></b> the preconditions for
247 calling the function
</dt>
249 <dt><b><a href=
"#effects">Effects:
</a></b> the actions performed by the
252 <dt><b><a href=
"#postconditions">Postconditions:
</a></b> the observable
253 results established by the function
</dt>
255 <dt><b><a href=
"#returns">Returns:
</a></b> a description of the value(s)
256 returned by the function
</dt>
258 <dt><b><a href=
"#throws">Throws:
</a></b> any exceptions thrown by the
259 function, and the conditions that would cause the exception
</dt>
261 <dt><b><a href=
"#complexity">Complexity:
</a></b> the time and/or space
262 complexity of the function
</dt>
264 <dt><b><a href=
"#rationale">Rationale:
</a></b> the rationale for the
265 function's design or existence
</dt>
268 <p>Complexity requirements specified in the library clauses are upper
269 bounds, and implementations that provide better complexity guarantees
270 satisfy the requirements.
</p>
272 <h4><a name=
"ref-cpp" id=
"ref-cpp">References to the C++ Standard
275 <h4><a name=
"ref-c" id=
"ref-c">References to the C Standard
278 <h3><a name=
"other" id=
"other">Other conventions
</a></h3>
280 <p>These conventions are for describing implementation-defined types, and
281 member functions.
</p>
283 <h4><a name=
"type-descs" id=
"type-descs">Type descriptions
</a></h4>
285 <p>The Requirements subclauses may describe names that are used to specify
286 constraints on template arguments.
</p>
288 <h2><a name=
"more" id=
"more">More Information
</a></h2>
290 <h3><a name=
"function-semantic-explanations" id=
291 "function-semantic-explanations">Function semantic element
292 explanations
</a></h3>
294 <p>The function semantic element description
<a href=
295 "#function-elements">above
</a> is taken directly from the C++ standard, and
296 is quite terse. Here is a more detailed explanation of each of the
299 <p>Note the use of the
<code><code
> ...
</code
></code> font tag
300 to distinguish actual C++ usage from English prose.
</p>
302 <h4><a name=
"requires" id=
"requires">Requires
</a></h4>
304 <p>Preconditions for calling the function, typically expressed as
305 predicates. The most common preconditions are requirements on the value of
306 arguments, often in the form of C++ expressions. For example,
</p>
309 <code>void limit( int * p, int min, int max );
</code>
312 <dl class=
"function-semantics">
313 <dt><b>Requires:
</b> <code>p !=
0 && min
<= max
</code></dt>
316 <p>Requirements already enforced by the C++ language rules (such as the
317 type of arguments) are not repeated in Requires paragraphs.
</p>
319 <h4><a name=
"effects" id=
"effects">Effects
</a></h4>
321 <p>The actions performed by the function, described either in prose or in
322 C++. A description in prose is often less limiting on implementors, but is
323 often less precise than C++ code.
</p>
325 <p>If an effect is specified in one of the other elements, particularly
326 <i>postconditions
</i>,
<i>returns
</i>, or
<i>throws
</i>, it is not also
327 described in the
<i>effects
</i> paragraph. Having only a single description
328 ensures that there is one and only one specification, and thus eliminates
329 the risk of divergence.
</p>
331 <h4><a name=
"postconditions" id=
"postconditions">Postconditions
</a></h4>
333 <p>The observable results of the function, such as the value of variables.
334 Postconditions are often expressed as predicates that are true after the
335 function completes, in the form of C++ expressions. For example:
</p>
338 void make_zero_if_negative( int
& x );
341 <dl class=
"function-semantics">
342 <dt><b>Postcondition:
</b> <code>x
>=
0</code></dt>
345 <h4><a name=
"returns" id=
"returns">Returns
</a></h4>
347 <p>The value returned by the function, usually in the form of a C++
348 expression. For example:
</p>
350 int sum( int x, int y );
353 <dl class=
"function-semantics">
354 <dt><b>Returns:
</b> <code>x + y
</code></dt>
357 <p>Only specify the return value; the type is already dictated by C++
360 <h4><a name=
"throws" id=
"throws">Throws
</a></h4>
362 <p>Specify both the type of exception thrown, and the condition that causes
363 the exception to be thrown. For example, the
<code>std::basic_string
</code>
367 void resize(size_type n, charT c);
370 <dl class=
"function-semantics">
371 <dt><b>Throws:
</b> <code>length_error
</code> if
<code>n
>
372 max_size()
</code>.
</dt>
375 <h4><a name=
"complexity" id=
"complexity">Complexity
</a></h4>
377 <p>Specifying the time and/or space complexity of a function is often not
378 desirable because it over-constrains implementors and is hard to specify
379 correctly. Complexity is thus often best left as a quality of
380 implementation issue.
</p>
382 <p>A library component, however, can become effectively non-portable if
383 there is wide variation in performance between conforming implementations.
384 Containers are a prime example. In these cases it becomes worthwhile to
385 specify complexity.
</p>
387 <p>Complexity is often specified in generalized
<a href=
388 "http://hissa.nist.gov/dads/HTML/bigOnotation.html">"Big-O"
391 <h4><a name=
"rationale" id=
"rationale">Rationale
</a></h4>
393 <p>Specifying the rationale for a function's design or existence can often
394 give users a lot of insight into why a library is designed the way it is.
395 More importantly, it can help prevent
"fixing" something that wasn't really
396 broken as the library matures.
</p>
398 <h2 id=
"web">Web Reference Documentation
</h2>
400 <p>Boost library documentation is often accessed via the World
401 Web. Using search engines, a page deep in the reference
402 content could be viewed without any further context.
403 Therefore, it is helpful to add extra context, such as the
404 following, to each page:
</p>
407 <li>Describe the enclosing namespace or use fully scoped
409 <li>Document required headers for each type or function.
410 <li>Link to relevant tutorial information.
411 <li>Link to related example code.
412 <li>Include the library name.
413 <li>Include navigation elements to the beginning of the
417 <p>It is also useful to consider the effectiveness of a
418 description in search engines. Terse or cryptic descriptions
419 are less likely to help the curious find a relevant function
422 <h2><a name=
"footnotes" id=
"footnotes">Footnotes
</a></h2>
425 <dt><a class=
"footnote" id=
"footnote1" href=
"#footnote1-location">(
1)
</a> To save
426 space, items that do not apply to a clause are omitted. For example, if a
427 clause does not specify any requirements, there will be no
"Requirements"
430 <dt><a class=
"footnote" id=
"footnote2" href=
"#footnote2-location">(
2)
</a> Although
431 in some cases the code is unambiguously the optimum implementation.
</dt>
433 <dt><a class=
"footnote" id=
"footnote3" href=
"#footnote3-location">(
3)
</a> To save
434 space, items that do not apply to a class are omitted. For example, if a
435 class does not specify any comparison functions, there will be no
436 "Comparison functions" subclause.
</dt>
438 <dt><a class=
"footnote" id=
"footnote4" href=
"#footnote4-location">(
4)
</a> To save
439 space, items that do not apply to a function are omitted. For example, if
440 a function does not specify any precondition, there will be no
"Requires"
445 <p><a href=
"http://validator.w3.org/check?uri=referer"><img border=
"0" src=
446 "../../doc/images/valid-html401.png" alt=
"Valid HTML 4.01 Transitional"
447 height=
"31" width=
"88"></a></p>
450 <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
451 December,
2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
453 <p><i>Copyright
© 2001 <a href=
454 "mailto:williamkempf@hotmail.com">William E. Kempf
</a></i></p>
456 <p><i>Distributed under the Boost Software License, Version
1.0. (See
457 accompanying file
<a href=
"../../LICENSE_1_0.txt">LICENSE_1_0.txt
</a> or
459 "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt
</a>)
</i></p>