A global identifier for this element Set to $Date: 2003/04/13 14:46:07 $ to keep "last revised" information in sync with CVS changes Implementation detail used by XIncludes The name of the element being declared to referenced The name of the file associated with this element The specifiers for this function, e.g., inline, static, etc. cv-qualifiers for this method, e.g., const volatile

template?, inherit*, purpose?, description?, (%boost.class.mix;)*

purpose?, description?, requires?, effects?, postconditions?, returns?, throws?, complexity?, notes?, rationale?

IGNORE

alt CDATA #IMPLIED

source*, lib*, requirement*, purpose, if-fails?

IGNORE

|library-reference|testsuite

xml:base CDATA #IMPLIED last-revision CDATA #IMPLIED id CDATA #IMPLIED

%local.common.attrib; id CDATA #IMPLIED

|using-namespace|using-class|librarylist|librarycategorylist

alt CDATA #IMPLIED

|functionname|libraryname|code

IGNORE

template-type-parameter|template-nontype-parameter|template-varargs

xml:base CDATA #IMPLIED last-revision CDATA #IMPLIED

IGNORE

|libraryinfo

template?, specialization?, inherit?, purpose?, description?, (%boost.class.mix;)*

libraryinfo, (title, ((section|library-reference|testsuite))+)?

A specialization (partial or full) of a class template name CDATA #REQUIRED %boost.common.attrib;

Declares a test that should compile and link filename CDATA #REQUIRED name CDATA #IMPLIED

Declares a test that should compile but fail to link filename CDATA #REQUIRED name CDATA #IMPLIED

Declares a typedef name CDATA #REQUIRED %boost.common.attrib;

Declares a static constant, e.g., const int foo = 5;. name CDATA #REQUIRED %boost.common.attrib;

Mimics the code tag in HTML Text within a code tag is generally typeset in a different, monospaced font so that it stands out as code. The code tag in BoostBook is transformed directly into the computeroutput tag in DocBook. %boost.common.attrib;

Declares a destructor for the enclosing class General documentation on functions in BoostBook is provided in the function element documentation. specifiers CDATA #IMPLIED %boost.common.attrib;

Declares a template type parameter name CDATA #REQUIRED %boost.common.attrib;

Detailed description of a construct Although the context model for this element is ANY, detailed descriptions should contain structured DocBook elements that occur within sections, e.g., paragraphs (para, simpara), lists (orderedlist, itemizedlist), tables (informaltable, table), etc. %boost.common.attrib;

Placeholder for an alphabetical list of libraries Developers aren't generally expected to use this element. Its existence is mainly as a placeholder in boost.xml for the alphabetical list of libraries. %boost.common.attrib;

Declares the reference material for a library 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">  </header> </library-reference> If the Any library contained multiple headers, we would list them all as children of the <library-reference> element. library-reference elements can be nested, so that reference material can be divided into separate sections that each contain different headers. %boost.common.attrib;

Defines a BoostBook book This element is the topmost level defined by boost.xml for all Boost documentation. It will not generally be used by developers. %boost.common.attrib;

Declares a C++ union or union template name CDATA #REQUIRED %boost.common.attrib;

Declares a base class of the enclosing class or struct This element contains the name of the class inherited. The content model is free-form, as the inherited class may be an instantiation of a template and may have markup in it (e.g., classname tags). access CDATA #REQUIRED %boost.common.attrib;

Declares a variable-length list of template parameters Variable-length template parameter lists are not allowed in C++, but because they are sometimes needed in documentation they are allowed in BoostBook. This element generally expands to "..." and can be used anywhere any other template parameter can be used. %boost.common.attrib;

Defines source code for a test This element will contain the source code for a testcase that will be generated from the documentation. To reduce the amount of escaping in the text, it is recommended to use CDATA sections, which look like this: <![CDATA[ <your program text here: no escaping needed!> ]]> In addition to CDATA sections, code snippets can be pulled in from programlisting elements using the snippet element.

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 CDATA #REQUIRED specifiers CDATA #IMPLIED %boost.common.attrib;

Conditions that must hold after the function returns %boost.common.attrib;

A testcase that should compile correctly filename CDATA #REQUIRED name CDATA #IMPLIED

Declares a method, i.e., a member function General documentation on functions in BoostBook is provided in the function element documentation. name CDATA #REQUIRED cv CDATA #IMPLIED specifiers CDATA #IMPLIED %boost.common.attrib;

Pulls in a code snippet from a programlisting element name CDATA #REQUIRED The name of the programlisting element to insert

Declares a constructor of the enclosing class General documentation on functions in BoostBook is provided in the function element documentation. specifiers CDATA #IMPLIED %boost.common.attrib;

Declares a namespace 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">  </namespace> </header> </library-reference> name CDATA #REQUIRED %boost.common.attrib;

What it means when a testcase fails Describes to the user the effect a certain failing testcase will have on the usefulness of a library. This field is useful in cases where a failed testcase does not mean that the library won't be useful, but may mean that certain library features will not be available.

A set of functions that are grouped together under one name name CDATA #REQUIRED %boost.common.attrib;

References a function with the given name If a function (or overloaded function) with the given, possibly-qualified name is found, this generates a link to that function. Lookups obey currently-active using-class and using-namespace directives to aid in the search, along with searching within the current scope. %boost.common.attrib;

Declares that the enclosing library is in this category name CDATA #REQUIRED %boost.common.attrib;

Non-normative notes about a function's semantics %boost.common.attrib;

Declares a data member of a class name CDATA #REQUIRED %boost.common.attrib;

Defines the specialization arguments for a class specialization %boost.common.attrib;

A specialization (full or partial) of a union template name CDATA #REQUIRED %boost.common.attrib;

Description of the exceptions thrown by a function %boost.common.attrib;

A template argument in a specialization %boost.common.attrib;

A set of methods that are grouped together under one name name CDATA #REQUIRED %boost.common.attrib;

A requirement/property in the Jamfile for a testcase A requirement is part of the dependencies of a target in a Jamfile. The name attribute of a requirement element gives the name of the Boost.Build feature and the content of the requirement gives the value of that feature. A requirement such as <includes>foo.hpp would be encoded as

<requirement
  name="includes">foo.hpp</requirement>

. name CDATA #REQUIRED

Conditions that must be met prior to executing a function %boost.common.attrib;

The type of a function parameter %boost.common.attrib;

Injects the method and function names of a class into the local scope name CDATA #REQUIRED %boost.common.attrib;

A testcase that should compile, link, and execute filename CDATA #REQUIRED name CDATA #IMPLIED

Describes in one short sentence or phrase the purpose of a library %boost.common.attrib;

Declares a copy-assignment operator The return type of the copy-assignment operator does not need to be specified. If left unspecified, it will default to an unqualified reference to the enclosing class type. General documentation on functions in BoostBook is provided in the function element documentation. cv CDATA #IMPLIED specifiers CDATA #IMPLIED %boost.common.attrib;

A testcase that should compile and link, but fail on execution filename CDATA #REQUIRED name CDATA #IMPLIED

Declares the template parameters of a class or function %boost.common.attrib;

A testcase that should fail to compile filename CDATA #REQUIRED name CDATA #IMPLIED

Description of the return value of a function %boost.common.attrib;

The default value of a function or template parameter %boost.common.attrib;

A function parameter name CDATA #IMPLIED

One signature of an overloaded function or method A signature refers to one declaration of an overloaded function or method. The signature itself has no name, because the name of the overloaded function or method is used. An overloaded function or method will have several signatures that will generally be typeset together. cv CDATA #IMPLIED specifiers CDATA #IMPLIED %boost.common.attrib;

An overloaded function General documentation on functions in BoostBook is provided in the function element documentation. name CDATA #REQUIRED %boost.common.attrib;

Declares a class or class template 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 a description element 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> Class templates are defined by <class> elements with a <template> child element at the beginning. name CDATA #REQUIRED %boost.common.attrib;

Defines a new library category All library category definitions should be in doc/src/boost.xml, and the names of categories must be prefixed with "category:". name CDATA #REQUIRED %boost.common.attrib;

The type of an element or return type of a function %boost.common.attrib;

A single value of an enumeration name CDATA #REQUIRED %boost.common.attrib;

An overloaded method General documentation on functions in BoostBook is provided in the function element documentation. name CDATA #REQUIRED %boost.common.attrib;

A sample of program code name CDATA #IMPLIED

The time/space/etc. complexity of a function %boost.common.attrib;

A short description of an entity's use %boost.common.attrib;

A nontype template parameter name CDATA #REQUIRED %boost.common.attrib;

Top-level element for a library name CDATA #REQUIRED dirname CDATA #REQUIRED html-only CDATA #IMPLIED url CDATA #IMPLIED %boost.common.attrib;

Categorized listing of libraries This element is not intended for use by developers, but is used by doc/src/boost.xml as a placeholder. %boost.common.attrib;

Injects the declared names from a namespace into the local scope name CDATA #REQUIRED %boost.common.attrib;

A specialization (full or partial) of a struct template name CDATA #REQUIRED %boost.common.attrib;

Declares a C++ struct name CDATA #REQUIRED %boost.common.attrib;

A library dependency Declares a library dependency on the library named by the content of this element, to be emitted in a Jamfile.

Declares an enumeration type name CDATA #REQUIRED %boost.common.attrib;

Declares the requirements of a function %boost.common.attrib;

Declares the side effects of a function %boost.common.attrib;

References a library of the given name %boost.common.attrib;

Provides information about a library %boost.common.attrib;

Describes a library testsuite %boost.common.attrib;

Declares a C++ header with the given name name CDATA #REQUIRED %boost.common.attrib;

Describes the rationale for a particular function's design %boost.common.attrib;