# 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