This section describes the documentation of C++ constructs within BoostBook. BoostBook provides elements that describe C++ classes, functions, namespaces, and other declarative constructs in a presentation-independent manner. From these descriptions, the BoostBook XSL stylesheets generate cross-referenced reference documentation for C++ libraries with a consistent look and feel. The basic scheme for documenting C++ elements in BoostBook is that the name of the XML element for a particular C++ construct matches the name of the C++ keyword (e.g., typedef, template, enum) or concept (e.g., constructor, class-specialization). Each attribute for a named declaration requires a name attribute that gives the name of the entity in C++. The content model of the elements then follows from the information provided in a C++ declaration, e.g., function parameter lists, type, default values, but each element may also contain a purpose element, containing a short description of the purpose of the entity begin described, and/or a description element, containing extended documentation.

Reference documentation for a library is contained with a <library-reference> element. The <library-reference> element has no attributes, and contains as children only <header> elements. The <header> element defines a C++ header file. Within each C++ header file lie the definitions of C++ constructs to be documented. The name attribute of the <header> element gives the name of the header, as one would specify when including the header. For instance, the <library-reference> for the Any library may look like this: <library-reference> <header name="boost/any.hpp"> <!-- C++ constructs in this header --> </header> </library-reference> If the Any library contained multiple headers, we would list them all as children of the <library-reference> element.

BoostBook namespaces are declared via the <namespace> element. As in C++, namespaces can be nested and contain other C++ constructs, such as classes or functions. The name attribute of a <namespace> element gives the namespace name (e.g., "boost"). The Any library is defined entirely within namespace boost by: <library-reference> <header name="boost/any.hpp"> <namespace name="boost"> <!-- C++ constructs in the boost namespace --> </namespace> </header> </library-reference>

C++ classes and class templates are described via the <class> element. Each class has a name (e.g., "any") given by the name attribute, a purpose given by the <purpose> element, documentation, and a set of types, functions, base classes, and data members. Here is a minimal definition of the boost::any class: <namespace name="boost"> <class name="any"> <purpose> A class whose instances can hold instances of any type that satisfies ValueType requirements. </purpose> </class> </namespace> Additional class documentation can be contained in <para> elements following the <purpose> element. This documentation will be typeset prior to documentation for specific elements in the class (e.g., constructors or methods). Class inheritance is described via the <inherit> element. The <inherit> element requires an access attribute which must be one of public, protected, or private. The content of the <inherited> element in C++ code that names the class inherited, and may contain markup to link to the class. The following description of the class boost::bad_any_cast describes public inheritance from the class std::bad_cast. It also defines the <purpose> element, which contains a short description of the use of the class. <class name="bad_any_cast"> <inherit access="public"><classname>std::bad_cast</classname></inherit> <purpose><para>The exception thrown in the event of a failed <functionname>any_cast</functionname> of an <classname>any</classname> value.</para></purpose> </class> Information about constructors, methods, and other functions can be found in . Note that free functions and free function groups are allowed at class level, and will be documented along with the class, for instance see the documentation of boost::any_cast. Class templates are defined by <class> elements with a <template> child element at the beginning.

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; gives the elements for each C++ function type. 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 names and uses of the XML elements for each clause type are given in . The following example illustrates some constructors and a destructor for boost::any. We note that in each of the clauses from there is a (required!) <simpara> element containing the text for that clause. We also 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> C++ Function BoostBook Element Constructor <constructor> Destructor <destructor> Copy assignment operator <copy-assignment> Member function <method> Free function <function> BoostBook element Description <requires> A set of requirements that must be met prior to execution of the function (a.k.a., preconditions). If any of these requirements is not met and the function is executed, then the behavior is undefined. <effects> The effects of executing the function. For instance, this may include documenting changes in state, other functions executed, or output written to files. <postconditions> Conditions that are guaranteed to hold after execution of the function, assuming that all requirements have been met. <returns> A description of the value returned from the function. <throws> A description of the exceptions that may be thrown from this function. <complexity> The computational complexity of this function. <notes> Additional notes that clarify the behavior of the function. <rationale> Reasons for the current semantics, including an explanation of potential alternative semantics and reasons why the alternatives have not bee used.