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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<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.htm"><img height="86" width="277" alt="C++ Boost" src="../../c++boost.gif" 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>
<dl class="page-index">
<dt><a href="#elements">Document elements</a></dt>
<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>
<dt><a href="#other">Other conventions</a></dt>
<dl class="page-index">
<dt><a href="#type-descs">Type descriptions</a></dt>
</dl>
</dl>
<dt><a href="#more">More Information</a></dt>
<dl class="page-index">
<dt><a href="#function-semantic-explanations">Function semantic element explanations</a></dt>
<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>
</dl>
<dt><a href="#footnotes">Footnotes</a></dt>
</dl>
<h2><a name="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">Standards Conforming</a> Documentation</h2>
<h3><a name="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">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">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">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">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">References to the C++ Standard library</a></h4>
<h4><a name="ref-c">References to the C Standard library</a></h4>
<h3><a name="other">Other conventions</a></h3>
<p>These conventions are for describing implementation-defined types, and member
functions.</p>
<h4><a name="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">More Information</a></h2>
<h3><a name="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">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,
<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">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">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">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.
<h4><a name="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:
<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">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">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">Footnotes</a></h2>
<dl>
<dt><a class="footnote" name="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">(2)</a> Although in some cases the
code is unambiguously the optimum implementation.</dt>
<dt><a class="footnote" name="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">(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>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
05 November, 2001
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
</p>
<p><i>© Copyright <a href="mailto:williamkempf@hotmail.com">William E. Kempf</a>
2001. All Rights Reserved.</i></p>
</body>
</html>
|
