...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
function
function — Declares a function
BoostBook functions are documented by specifying the function's interface (e.g., its C++ signature) and its behavior. Constructors, destructors, member functions, and free functions all use the same documentation method, although the top-level tags differ.
The behavior of functions in BoostBook is documenting using a style similar to that of the C++ standard, with clauses describing the requirements, effects, postconditions, exception behavior, and return values of functions.
The following example illustrates some constructors and a
destructor for boost::any
. Note that one of
the constructors takes a single parameter whose name is "other" and
whose type, const any&
is contained in the
<paramtype> element; any number of parameters may be specified
in this way.
<class name="any"> <constructor> <postconditions><para><this->empty()></para></postconditions> </constructor> <constructor> <parameter name="other"> <paramtype>const <classname>any</classname>&</paramtype> </parameter> <effects> <simpara> Copy constructor that copies content of <code>other</code> into the new instance, so that any content is equivalent in both type and value to the content of <code>other</code>, or empty if <code>other</code> is empty. </simpara> </effects> <throws> <simpara>May fail with a <classname>std::bad_alloc</classname> exception or any exceptions arising from the copy constructor of the contained type. </simpara> </throws> </constructor> <destructor> <effects><simpara>Releases any and all resources used in management of instance.</simpara></effects> <throws><simpara>Nothing.</simpara></throws> </destructor> </class>
Name | Type | Value | Purpose |
---|---|---|---|
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes |
specifiers | #IMPLIED | CDATA | The specifiers for this function, e.g., inline, static, etc. |
name | #REQUIRED | CDATA | The name of the element being declared to referenced |
id | #IMPLIED | CDATA | A global identifier for this element |
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes |