1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
|
<!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>
|
