BoostBook element function

| Home | Libraries | People | FAQ | More

## 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