Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Click here to view the latest version of this page.
PrevUpHomeNext

BoostBook element function

function — Declares a function

Synopsis

function ::= (template?, type, parameter*, purpose?, description?, requires?, effects?, postconditions?, returns?, throws?, complexity?, notes?, rationale?)

Description

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>&amp;</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>

Attributes

Name Type Value Purpose
last-revision #IMPLIED CDATA Set to $Date: 2009-10-10 15:53:46 +0100 (Sat, 10 Oct 2009) $ 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

PrevUpHomeNext