[ceph.git] / ceph / src / boost / more / writingdoc / structure.html

<!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 &sect;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>&lt;code&gt; ... &lt;/code&gt;</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 &amp;&amp; min &lt;= 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 &amp; x );
</pre>

  <dl class="function-semantics">
    <dt><b>Postcondition:</b> <code>x &gt;= 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 &gt;
    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 &copy; 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>
Commit	Line	Data
7c673cae FG	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="#web">Web Reference Documentation</a></dt>
94
95	<dt><a href="#footnotes">Footnotes</a></dt>
96	</dl>
97
98	<h2><a name="introduction" id="introduction">Introduction</a></h2>
99
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
112	documentation.</p>
113
114	<h2><a name="standards-conforming" id="standards-conforming">Standards
115	Conforming</a> Documentation</h2>
116
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>
126
127	<h3><a name="elements" id="elements">Document elements</a></h3>
128
129	<p>Each document contains the following elements, as applicable<a class=
130	"footnote" href="#footnote1" id="footnote1-location">(1)</a>:</p>
131
132	<ul>
133	<li><a href="#summary">Summary</a></li>
134
135	<li><a href="#requirements">Requirements</a></li>
136
137	<li><a href="#detailed-specs">Detailed specifications</a></li>
138
139	<li><a href="#ref-cpp">References to the Standard C++ library</a></li>
140
141	<li><a href="#ref-c">References to the Standard C library</a></li>
142	</ul>
143
144	<h4><a name="summary" id="summary">Summary</a></h4>
145
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
149	each header.</p>
150
151	<p>Paragraphs labeled "Note(s):" or "Example(s):" are informative, other
152	paragraphs are normative.</p>
153
154	<p>The summary and the detailed specifications are presented in the
155	order:</p>
156
157	<ul>
158	<li>Macros</li>
159
160	<li>Values</li>
161
162	<li>Types</li>
163
164	<li>Classes</li>
165
166	<li>Functions</li>
167
168	<li>Objects</li>
169	</ul>
170
171	<h4><a name="requirements" id="requirements">Requirements</a></h4>
172
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>
176
177	<ul>
178	<li>Template arguments</li>
179
180	<li>Derived classes</li>
181
182	<li>Containers, iterators, and/or algorithms that meet an interface
183	convention</li>
184	</ul>
185
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>
191
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
197	type parameters.</p>
198
199	<p>Template argument requirements are sometimes referenced by name.</p>
200
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>
205
206	<h4><a name="detailed-specs" id="detailed-specs">Detailed
207	specification</a></h4>
208
209	<p>The detailed specifications each contain the following elements:</p>
210
211	<ul>
212	<li>Name and brief description</li>
213
214	<li>Synopsis (class definition or function prototype, as
215	appropriate)</li>
216
217	<li>Restrictions on template arguments, if any</li>
218
219	<li>Description of class invariants</li>
220
221	<li>Description of function semantics</li>
222	</ul>
223
224	<p>Descriptions of class member functions follow the order (as
225	appropriate)<a class="footnote" href="#footnote3" id="footnote3-location">(3)</a>:</p>
226
227	<ul>
228	<li>Constructor(s) and destructor</li>
229
230	<li>Copying and assignment functions</li>
231
232	<li>Comparison functions</li>
233
234	<li>Modifier functions</li>
235
236	<li>Observer functions</li>
237
238	<li>Operators and other non-member functions</li>
239	</ul>
240
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>
244
245	<dl class="function-semantics">
246	<dt><b><a href="#requires">Requires:</a></b> the preconditions for
247	calling the function</dt>
248
249	<dt><b><a href="#effects">Effects:</a></b> the actions performed by the
250	function</dt>
251
252	<dt><b><a href="#postconditions">Postconditions:</a></b> the observable
253	results established by the function</dt>
254
255	<dt><b><a href="#returns">Returns:</a></b> a description of the value(s)
256	returned by the function</dt>
257
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>
260
261	<dt><b><a href="#complexity">Complexity:</a></b> the time and/or space
262	complexity of the function</dt>
263
264	<dt><b><a href="#rationale">Rationale:</a></b> the rationale for the
265	function's design or existence</dt>
266	</dl>
267
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>
271
272	<h4><a name="ref-cpp" id="ref-cpp">References to the C++ Standard
273	library</a></h4>
274
275	<h4><a name="ref-c" id="ref-c">References to the C Standard
276	library</a></h4>
277
278	<h3><a name="other" id="other">Other conventions</a></h3>
279
280	<p>These conventions are for describing implementation-defined types, and
281	member functions.</p>
282
283	<h4><a name="type-descs" id="type-descs">Type descriptions</a></h4>
284
285	<p>The Requirements subclauses may describe names that are used to specify
286	constraints on template arguments.</p>
287
288	<h2><a name="more" id="more">More Information</a></h2>
289
290	<h3><a name="function-semantic-explanations" id=
291	"function-semantic-explanations">Function semantic element
292	explanations</a></h3>
293
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
297	elements.</p>
298
299	<p>Note the use of the <code><code> ... </code></code> font tag
300	to distinguish actual C++ usage from English prose.</p>
301
302	<h4><a name="requires" id="requires">Requires</a></h4>
303
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>
307	<pre>
308
309	<code>void limit( int * p, int min, int max );</code>
310	</pre>
311
312	<dl class="function-semantics">
313	<dt><b>Requires:</b> <code>p != 0 && min <= max</code></dt>
314	</dl>
315
316	<p>Requirements already enforced by the C++ language rules (such as the
317	type of arguments) are not repeated in Requires paragraphs.</p>
318
319	<h4><a name="effects" id="effects">Effects</a></h4>
320
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>
324
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>
330
331	<h4><a name="postconditions" id="postconditions">Postconditions</a></h4>
332
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>
336	<pre>
337
338	void make_zero_if_negative( int & x );
339	</pre>
340
341	<dl class="function-semantics">
342	<dt><b>Postcondition:</b> <code>x >= 0</code></dt>
343	</dl>
344
345	<h4><a name="returns" id="returns">Returns</a></h4>
346
347	<p>The value returned by the function, usually in the form of a C++
348	expression. For example:</p>
349	<pre>
350	int sum( int x, int y );
351	</pre>
352
353	<dl class="function-semantics">
354	<dt><b>Returns:</b> <code>x + y</code></dt>
355	</dl>
356
357	<p>Only specify the return value; the type is already dictated by C++
358	language rules.</p>
359
360	<h4><a name="throws" id="throws">Throws</a></h4>
361
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>
364	class specifies:</p>
365	<pre>
366
367	void resize(size_type n, charT c);
368	</pre>
369
370	<dl class="function-semantics">
371	<dt><b>Throws:</b> <code>length_error</code> if <code>n >
372	max_size()</code>.</dt>
373	</dl>
374
375	<h4><a name="complexity" id="complexity">Complexity</a></h4>
376
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>
381
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>
386
387	<p>Complexity is often specified in generalized <a href=
388	"http://hissa.nist.gov/dads/HTML/bigOnotation.html">"Big-O"
389	notation</a>.</p>
390
391	<h4><a name="rationale" id="rationale">Rationale</a></h4>
392
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>
397
398	<h2 id="web">Web Reference Documentation</h2>
399
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>
405
406	<ul>
407	<li>Describe the enclosing namespace or use fully scoped
408	identifiers.
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
414	documentation.
415	</ul>
416
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
420	or type.</p>
421
422	<h2><a name="footnotes" id="footnotes">Footnotes</a></h2>
423
424	<dl>
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"
428	subclause.</dt>
429
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>
432
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>
437
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"
441	paragraph.</dt>
442	</dl>
443	<hr>
444
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>
448
449	<p>Revised
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>
452
453	<p><i>Copyright © 2001 <a href=
454	"mailto:williamkempf@hotmail.com">William E. Kempf</a></i></p>
455
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
458	copy at <a href=
459	"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
460	</body>
461	</html>