# Reference

Elements:

- Element access - Declares an access specification for class members

- Element boostbook - Defines a BoostBook book

- Element class - Declares a class or class template

- Element class-specialization - A specialization (partial or full) of a class template

- Element code - Mimics the code tag in HTML

- Element compile-fail-test - A testcase that should fail to compile

- Element compile-test - A testcase that should compile correctly

- Element complexity - The time/space/etc. complexity of a function

- Element constructor - Declares a constructor of the enclosing class

- Element copy-assignment - Declares a copy-assignment operator

- Element data-member - Declares a data member of a class

- Element default - The default value of a function or template parameter

- Element description - Detailed description of a construct

- Element destructor - Declares a destructor for the enclosing class

- Element effects - Declares the side effects of a function

- Element enum - Declares an enumeration type

- Element enumname - References an enumeration type with the given name

- Element enumvalue - A single value of an enumeration

- Element free-function-group - A set of functions that are grouped together under one name

- Element function - Declares a function

- Element functionname - References a function with the given name

- Element globalname - References a global with the given name

- Element header - Declares a C++ header with the given name

- Element headername - References a C++ header with the given name

- Element if-fails - What it means when a testcase fails

- Element inherit - Declares a base class of the enclosing class or struct

- Element lib - A library dependency

- Element library - Top-level element for a library

- Element library-reference - Declares the reference material for a library

- Element librarycategory - Declares that the enclosing library is in this category

- Element librarycategorydef - Defines a new library category

- Element librarycategorylist - Categorized listing of libraries

- Element libraryinfo - Provides information about a library

- Element librarylist - Placeholder for an alphabetical list of libraries

- Element libraryname - References a library of the given name

- Element librarypurpose - Describes in one short sentence or phrase the purpose of a library

- Element link-fail-test - Declares a test that should compile but fail to link

- Element link-test - Declares a test that should compile and link

- Element macroname - References a macro with the given name

- Element method - Declares a method, i.e., a member function

- Element method-group - A set of methods that are grouped together under one name

- Element namespace - Declares a namespace

- Element notes - Non-normative notes about a function's semantics

- Element overloaded-function - An overloaded function

- Element overloaded-method - An overloaded method

- Element parameter - A function parameter

- Element paramtype - The type of a function parameter

- Element postconditions - Conditions that must hold after the function returns

- Element precondition - Conditions that must be met prior to executing a function

- Element programlisting - A sample of program code

- Element purpose - A short description of an entity's use

- Element rationale - Describes the rationale for a particular function's design

- Element requirement - A requirement/property in the Jamfile for a testcase

- Element requires - Declares the requirements of a function

- Element returns - Description of the return value of a function

- Element run-fail-test - A testcase that should compile and link, but fail on execution

- Element run-test - A testcase that should compile, link, and execute

- Element signature - One signature of an overloaded function or method

- Element snippet - Pulls in a code snippet from a programlisting element

- Element source - Defines source code for a test

- Element specialization - Defines the specialization arguments for a class specialization

- Element static-constant - Declares a static constant, e.g., `const int foo = 5;`.

- Element struct - Declares a C++ struct

- Element struct-specialization - A specialization (full or partial) of a struct template

- Element template - Declares the template parameters of a class or function

- Element template-arg - A template argument in a specialization

- Element template-nontype-parameter - A nontype template parameter

- Element template-type-parameter - Declares a template type parameter

- Element template-varargs - Declares a variable-length list of template parameters

- Element testsuite - Describes a library testsuite

- Element throws - Description of the exceptions thrown by a function

- Element type - The type of an element or return type of a function

- Element typedef - Declares a typedef

- Element union - Declares a C++ union or union template

- Element union-specialization - A specialization (full or partial) of a union template

- Element using-class - Injects the method and function names of a class into the local scope

- Element using-namespace - Injects the declared names from a namespace into the local scope

BoostBook element class-specialization 9
class-specialization A specialization (partial or full) of a class template
class-specialization ::= (template?, specialization?, inherit?, purpose?, description?, (access| static-constant| typedef| enum| copy-assignment| constructor| destructor| method-group| free-function-group| function| method| overloaded-function| overloaded-method| data-member| class| class-specialization| struct| struct-specialization| union| union-specialization)*)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element link-test 9
link-test Declares a test that should compile and link
link-test ::= (source*, lib*, requirement*, purpose, if-fails?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
filename | #REQUIRED | CDATA | The name of the file associated with this element
name | #IMPLIED | CDATA | The name of the element being declared to referenced

BoostBook element link-fail-test 9
link-fail-test Declares a test that should compile but fail to link
link-fail-test ::= (source*, lib*, requirement*, purpose, if-fails?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
filename | #REQUIRED | CDATA | The name of the file associated with this element
name | #IMPLIED | CDATA | The name of the element being declared to referenced

BoostBook element typedef 9
typedef Declares a typedef
typedef ::= (type, purpose?, description?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element static-constant 9
static-constant Declares a static constant, e.g., `const int foo = 5;`.
static-constant ::= (type, default, purpose?, description?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element code 9
code Mimics the code tag in HTML
code ::= (ANY)

### Description

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.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element destructor 9
destructor Declares a destructor for the enclosing class
destructor ::= (purpose?, description?, requires?, effects?, postconditions?, returns?, throws?, complexity?, notes?, rationale?)

### Description

General documentation on functions in BoostBook is provided in the function element documentation.

### Attributes

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.
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element template-type-parameter 9
template-type-parameter Declares a template type parameter
template-type-parameter ::= (default?, purpose?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
pack | #IMPLIED | CDATA | Set to '1' if the parameter is a parameter pack.
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

BoostBook element description 9
description Detailed description of a construct
description ::= (ANY)

### Description

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.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element librarylist 9
librarylist Placeholder for an alphabetical list of libraries
librarylist ::= EMPTY

### Description

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.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element library-reference 9
library-reference Declares the reference material for a library
library-reference ::= (title?, section*, (header| library-reference)*)

### Description

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.

library-reference elements can be nested, so that reference material can be divided into separate sections that each contain different headers.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element boostbook 9
boostbook Defines a BoostBook book
boostbook ::= (title, (chapter| library)*)

### Description

This element is the topmost level defined by `boost.xml` for all Boost documentation. It will not generally be used by developers.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element union 9
union Declares a C++ union or union template
union ::= (template?, inherit*, purpose?, description?, (access| static-constant| typedef| enum| copy-assignment| constructor| destructor| method-group| free-function-group| function| method| overloaded-function| overloaded-method| data-member| class| class-specialization| struct| struct-specialization| union| union-specialization)*)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element inherit 9
inherit Declares a base class of the enclosing class or struct
inherit ::= (type, purpose?)

### Description

This element contains the type of the class inherited.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
access | #IMPLIED | CDATA | The access specifier ("public", "private", or "protected") of the inheritance.
id | #IMPLIED | CDATA | A global identifier for this element
pack | #IMPLIED | CDATA | Set to '1' if this is a pack exapansion.
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element template-varargs 9
template-varargs Declares a variable-length list of template parameters
template-varargs ::= EMPTY

### Description

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.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element source 9
source Defines source code for a test
source ::= (#PCDATA| snippet)*

### Description

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.

BoostBook element function 9
function Declares a function
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$ 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

BoostBook element macroname 9
macroname
macroname ::= (#PCDATA)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
alt | #IMPLIED | CDATA |
id | #IMPLIED | CDATA | A global identifier for this element

BoostBook element postconditions 9
postconditions Conditions that must hold after the function returns
postconditions ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element compile-test 9
compile-test A testcase that should compile correctly
compile-test ::= (source*, lib*, requirement*, purpose, if-fails?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
filename | #REQUIRED | CDATA | The name of the file associated with this element
name | #IMPLIED | CDATA | The name of the element being declared to referenced

BoostBook element method 9
method Declares a method, i.e., a member function
method ::= (template?, type, parameter*, purpose?, description?, requires?, effects?, postconditions?, returns?, throws?, complexity?, notes?, rationale?)

### Description

General documentation on functions in BoostBook is provided in the function element documentation.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
cv | #IMPLIED | CDATA | cv-qualifiers for this method, e.g., const volatile
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

BoostBook element snippet 9
snippet Pulls in a code snippet from a programlisting element
snippet ::= EMPTY

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
name | #REQUIRED | CDATA | The name of the programlisting element to insert

BoostBook element constructor 9
constructor Declares a constructor of the enclosing class
constructor ::= (template?, parameter*, purpose?, description?, requires?, effects?, postconditions?, returns?, throws?, complexity?, notes?, rationale?)

### Description

General documentation on functions in BoostBook is provided in the function element documentation.

### Attributes

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.
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element namespace 9
namespace Declares a namespace
namespace ::= (class| class-specialization| struct| struct-specialization| union| union-specialization| typedef| enum| free-function-group| function| overloaded-function| namespace)*

### Description

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>

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element if-fails 9
if-fails What it means when a testcase fails
if-fails ::= (ANY)

### Description

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.

BoostBook element headername 9
headername
headername ::= (#PCDATA)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
alt | #IMPLIED | CDATA |
id | #IMPLIED | CDATA | A global identifier for this element

BoostBook element free-function-group 9
free-function-group A set of functions that are grouped together under one name
free-function-group ::= (function| overloaded-function)*

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element functionname 9
functionname References a function with the given name
functionname ::= (#PCDATA)

### Description

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.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
alt | #IMPLIED | CDATA |
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element librarycategory 9
librarycategory Declares that the enclosing library is in this category
librarycategory ::= (#PCDATA)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element notes 9
notes Non-normative notes about a function's semantics
notes ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element data-member 9
data-member Declares a data member of a class
data-member ::= (type, purpose?, description?)

### Attributes

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

BoostBook element specialization 9
specialization Defines the specialization arguments for a class specialization
specialization ::= (template-arg)*

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element union-specialization 9
union-specialization A specialization (full or partial) of a union template
union-specialization ::= (template?, specialization?, inherit?, purpose?, description?, (access| static-constant| typedef| enum| copy-assignment| constructor| destructor| method-group| free-function-group| function| method| overloaded-function| overloaded-method| data-member| class| class-specialization| struct| struct-specialization| union| union-specialization)*)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element throws 9
throws Description of the exceptions thrown by a function
throws ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element template-arg 9
template-arg A template argument in a specialization
template-arg ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
pack | #IMPLIED | CDATA | Set to '1' if this is a pack exapansion.
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element globalname 9
globalname
globalname ::= (#PCDATA)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
alt | #IMPLIED | CDATA |
id | #IMPLIED | CDATA | A global identifier for this element

BoostBook element method-group 9
method-group A set of methods that are grouped together under one name
method-group ::= (method| overloaded-method)*

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element requirement 9
requirement A requirement/property in the Jamfile for a testcase
requirement ::= (#PCDATA)

### Description

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>`.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
name | #REQUIRED | CDATA | The name of the element being declared to referenced

BoostBook element precondition 9
precondition Conditions that must be met prior to executing a function
precondition ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element paramtype 9
paramtype The type of a function parameter
paramtype ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element using-class 9
using-class Injects the method and function names of a class into the local scope
using-class ::= EMPTY

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element run-test 9
run-test A testcase that should compile, link, and execute
run-test ::= (source*, lib*, requirement*, purpose, if-fails?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
filename | #REQUIRED | CDATA | The name of the file associated with this element
name | #IMPLIED | CDATA | The name of the element being declared to referenced

BoostBook element librarypurpose 9
librarypurpose Describes in one short sentence or phrase the purpose of a library
librarypurpose ::= (#PCDATA| code| ulink| functionname| methodname| classname| macroname| headername| enumname| globalname)*

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element copy-assignment 9
copy-assignment Declares a copy-assignment operator
copy-assignment ::= (template?, type?, parameter*, purpose?, description?, requires?, effects?, postconditions?, returns?, throws?, complexity?, notes?, rationale?)

### Description

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.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
cv | #IMPLIED | CDATA | cv-qualifiers for this method, e.g., const volatile
specifiers | #IMPLIED | CDATA | The specifiers for this function, e.g., inline, static, etc.
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element run-fail-test 9
run-fail-test A testcase that should compile and link, but fail on execution
run-fail-test ::= (source*, lib*, requirement*, purpose, if-fails?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
filename | #REQUIRED | CDATA | The name of the file associated with this element
name | #IMPLIED | CDATA | The name of the element being declared to referenced

BoostBook element template 9
template Declares the template parameters of a class or function
template ::= (template-type-parameter| template-nontype-parameter| template-varargs)*

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element compile-fail-test 9
compile-fail-test A testcase that should fail to compile
compile-fail-test ::= (source*, lib*, requirement*, purpose, if-fails?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
filename | #REQUIRED | CDATA | The name of the file associated with this element
name | #IMPLIED | CDATA | The name of the element being declared to referenced

BoostBook element returns 9
returns Description of the return value of a function
returns ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element default 9
default The default value of a function or template parameter
default ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element parameter 9
parameter A function parameter
parameter ::= (paramtype, default?, description?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
name | #IMPLIED | CDATA | The name of the element being declared to referenced
pack | #IMPLIED | CDATA | Set to '1' if the parameter is a parameter pack.

BoostBook element signature 9
signature One signature of an overloaded function or method
signature ::= (template?, type, parameter*)

### Description

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.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
cv | #IMPLIED | CDATA | cv-qualifiers for this method, e.g., const volatile
specifiers | #IMPLIED | CDATA | The specifiers for this function, e.g., inline, static, etc.
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element overloaded-function 9
overloaded-function An overloaded function
overloaded-function ::= (signature*, purpose?, description?, requires?, effects?, postconditions?, returns?, throws?, complexity?, notes?, rationale?)

### Description

General documentation on functions in BoostBook is provided in the function element documentation.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element access 9
access Declares an access specification for class members
access ::= (static-constant| typedef| enum| copy-assignment| constructor| destructor| method-group| method| overloaded-method| data-member| class| class-specialization| struct| struct-specialization| union| union-specialization)+

### Description

The access specifications of class members (public, private, or protected) may be determined by enclosing them in an <access> element.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
name | #REQUIRED | CDATA | The name of the access specification, e.g. "public", "private", or "protected".
id | #IMPLIED | CDATA | A global identifier for this element

BoostBook element class 9
class Declares a class or class template
class ::= (template?, inherit*, purpose?, description?, (access| static-constant| typedef| enum| copy-assignment| constructor| destructor| method-group| free-function-group| function| method| overloaded-function| overloaded-method| data-member| class| class-specialization| struct| struct-specialization| union| union-specialization)*)

### Description

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.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element librarycategorydef 9
librarycategorydef Defines a new library category
librarycategorydef ::= (#PCDATA)

### Description

All library category definitions should be in `doc/src/boost.xml`, and the names of categories must be prefixed with "`category:`".

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element type 9
type The type of an element or return type of a function
type ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element enumvalue 9
enumvalue A single value of an enumeration
enumvalue ::= (default?, purpose?, description?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element overloaded-method 9
overloaded-method An overloaded method
overloaded-method ::= (signature*, purpose?, description?, requires?, effects?, postconditions?, returns?, throws?, complexity?, notes?, rationale?)

### Description

General documentation on functions in BoostBook is provided in the function element documentation.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element programlisting 9
programlisting A sample of program code
programlisting ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
name | #IMPLIED | CDATA | The name of the element being declared to referenced

BoostBook element complexity 9
complexity The time/space/etc. complexity of a function
complexity ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element purpose 9
purpose A short description of an entity's use
purpose ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element template-nontype-parameter 9
template-nontype-parameter A nontype template parameter
template-nontype-parameter ::= (type, default?, purpose?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
pack | #IMPLIED | CDATA | Set to '1' if the parameter is a parameter pack.
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

BoostBook element library 9
library Top-level element for a library
library ::= (libraryinfo, (title, ((section| library-reference| testsuite))+)?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
dirname | #REQUIRED | CDATA |
url | #IMPLIED | CDATA |
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
html-only | #IMPLIED | CDATA |

BoostBook element librarycategorylist 9
librarycategorylist Categorized listing of libraries
librarycategorylist ::= (librarycategorydef)*

### Description

This element is not intended for use by developers, but is used by `doc/src/boost.xml` as a placeholder.

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element using-namespace 9
using-namespace Injects the declared names from a namespace into the local scope
using-namespace ::= EMPTY

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element enumname 9
enumname
enumname ::= (#PCDATA)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
alt | #IMPLIED | CDATA |
id | #IMPLIED | CDATA | A global identifier for this element

BoostBook element struct-specialization 9
struct-specialization A specialization (full or partial) of a struct template
struct-specialization ::= (template?, specialization?, inherit?, purpose?, description?, (access| static-constant| typedef| enum| copy-assignment| constructor| destructor| method-group| free-function-group| function| method| overloaded-function| overloaded-method| data-member| class| class-specialization| struct| struct-specialization| union| union-specialization)*)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element struct 9
struct Declares a C++ struct
struct ::= (template?, inherit*, purpose?, description?, (access| static-constant| typedef| enum| copy-assignment| constructor| destructor| method-group| free-function-group| function| method| overloaded-function| overloaded-method| data-member| class| class-specialization| struct| struct-specialization| union| union-specialization)*)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element lib 9
lib A library dependency
lib ::= (#PCDATA)

### Description

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

BoostBook element enum 9
enum Declares an enumeration type
enum ::= (enumvalue*, purpose?, description?)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element requires 9
requires Declares the requirements of a function
requires ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element effects 9
effects Declares the side effects of a function
effects ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element libraryname 9
libraryname References a library of the given name
libraryname ::= (#PCDATA)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element libraryinfo 9
libraryinfo Provides information about a library
libraryinfo ::= (author+, copyright*, legalnotice*, librarypurpose, librarycategory*)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element testsuite 9
testsuite Describes a library testsuite
testsuite ::= ((compile-test| link-test| run-test| compile-fail-test| link-fail-test| run-fail-test)+)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes

BoostBook element header 9
header Declares a C++ header with the given name
header ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
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

BoostBook element rationale 9
rationale Describes the rationale for a particular function's design
rationale ::= (ANY)

### Attributes

Name | Type | Value | Purpose
--- | --- | --- | ---
last-revision | #IMPLIED | CDATA | Set to $Date$ to keep "last revised" information in sync with CVS changes
id | #IMPLIED | CDATA | A global identifier for this element
xml:base | #IMPLIED | CDATA | Implementation detail used by XIncludes