mirror of
https://github.com/boostorg/boostbook.git
synced 2025-05-09 15:03:57 +00:00
reference.dtdxml: The BoostBook DTD, converted to XML and documented
reference.xml: generated from reference.dtdxml reference_doc.xml: Useless now that we have reference.dtdxml boostbook.xml: Include reference.xml, not reference_doc.xml [SVN r18130]
This commit is contained in:
Douglas Gregor
parent
86b50f5b1d
commit
edc06baa80
@ -350,6 +350,6 @@ boostbook any : any.doxygen ;</programlisting>
|
||||
</section>
|
||||
|
||||
<xi:include href="documenting.xml"/>
|
||||
<xi:include href="reference_doc.xml"/>
|
||||
<xi:include href="together.xml"/>
|
||||
<xi:include href="reference.xml"/>
|
||||
</chapter>
|
||||
3226
doc/reference.dtdxml
Normal file
3226
doc/reference.dtdxml
Normal file
File diff suppressed because it is too large
Load Diff
2761
doc/reference.xml
Normal file
2761
doc/reference.xml
Normal file
File diff suppressed because one or more lines are too long
@ -1,304 +0,0 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
||||
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
||||
<section xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook.reference"
|
||||
last-revision="$Date$">
|
||||
<title>Documenting C++ Constructs</title>
|
||||
|
||||
<para>This section describes the documentation of C++ constructs
|
||||
within BoostBook. BoostBook provides elements that describe C++
|
||||
classes, functions, namespaces, and other declarative constructs in
|
||||
a presentation-independent manner. From these descriptions, the
|
||||
BoostBook XSL stylesheets generate cross-referenced reference
|
||||
documentation for C++ libraries with a consistent look and
|
||||
feel.</para>
|
||||
|
||||
<para>The basic scheme for documenting C++ elements in BoostBook is
|
||||
that the name of the XML element for a particular C++ construct
|
||||
matches the name of the C++ keyword (e.g.,
|
||||
<sgmltag>typedef</sgmltag>, <sgmltag>template</sgmltag>,
|
||||
<sgmltag>enum</sgmltag>) or concept (e.g.,
|
||||
<sgmltag>constructor</sgmltag>,
|
||||
<sgmltag>class-specialization</sgmltag>). Each attribute for a named
|
||||
declaration requires a <code>name</code> attribute that gives the
|
||||
name of the entity in C++. The content model of the elements then
|
||||
follows from the information provided in a C++ declaration, e.g.,
|
||||
function parameter lists, type, default values, but each element may
|
||||
also contain a <sgmltag>purpose</sgmltag> element, containing a
|
||||
short description of the purpose of the entity begin described,
|
||||
and/or a <sgmltag>description</sgmltag> element, containing extended
|
||||
documentation.</para>
|
||||
|
||||
<section>
|
||||
<title>Library references and headers</title>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>The <header> element defines a C++ header file. Within
|
||||
each C++ header file lie the definitions of C++ constructs to be
|
||||
documented. The <code>name</code> 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 <libraryname>Any</libraryname> library may look like
|
||||
this:</para>
|
||||
|
||||
<programlisting>
|
||||
<library-reference>
|
||||
<header name="boost/any.hpp">
|
||||
<!-- C++ constructs in this header -->
|
||||
</header>
|
||||
</library-reference>
|
||||
</programlisting>
|
||||
|
||||
<para>If the <libraryname>Any</libraryname> library contained
|
||||
multiple headers, we would list them all as children of the
|
||||
<library-reference> element.</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Namespaces</title>
|
||||
|
||||
<para>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 <code>name</code>
|
||||
attribute of a <namespace> element gives the namespace name
|
||||
(e.g., "boost"). The <libraryname>Any</libraryname> library is
|
||||
defined entirely within namespace boost by:</para>
|
||||
|
||||
<programlisting>
|
||||
<library-reference>
|
||||
<header name="boost/any.hpp">
|
||||
<namespace name="boost">
|
||||
<!-- C++ constructs in the boost namespace -->
|
||||
</namespace>
|
||||
</header>
|
||||
</library-reference>
|
||||
</programlisting>
|
||||
</section>
|
||||
|
||||
<section id="boostbook.classes">
|
||||
<title>Classes</title>
|
||||
|
||||
<para>C++ classes and class templates are described via the
|
||||
<class> element. Each class has a name (e.g., "any") given
|
||||
by the <code>name</code> 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 <classname>boost::any</classname> class:</para>
|
||||
<programlisting>
|
||||
<namespace name="boost">
|
||||
<class name="any">
|
||||
<purpose>
|
||||
A class whose instances can hold instances of any type that satisfies
|
||||
ValueType requirements.
|
||||
</purpose>
|
||||
</class>
|
||||
</namespace>
|
||||
</programlisting>
|
||||
|
||||
<para>Additional class documentation can be contained in
|
||||
<para> elements following the <purpose> element. This
|
||||
documentation will be typeset prior to documentation for specific
|
||||
elements in the class (e.g., constructors or methods).</para>
|
||||
|
||||
<para>Class inheritance is described via the <inherit>
|
||||
element. The <inherit> element requires an
|
||||
<code>access</code> attribute which must be one of
|
||||
<emphasis>public</emphasis>, <emphasis>protected</emphasis>, or
|
||||
<emphasis>private</emphasis>. 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 <classname>boost::bad_any_cast</classname> describes
|
||||
public inheritance from the class
|
||||
<classname>std::bad_cast</classname>. It also defines the
|
||||
<purpose> element, which contains a short description of the
|
||||
use of the class.</para>
|
||||
|
||||
<programlisting>
|
||||
<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>
|
||||
</programlisting>
|
||||
|
||||
<para>Information about constructors, methods, and other functions
|
||||
can be found in <xref linkend="boostbook.functions"/>. Note that
|
||||
free functions and free function groups are allowed at class
|
||||
level, and will be documented along with the class, for instance
|
||||
see the documentation of
|
||||
<functionname>boost::any_cast</functionname>.</para>
|
||||
|
||||
<para>Class templates are defined by <class> elements with a
|
||||
<template> child element at the beginning.</para>
|
||||
</section>
|
||||
|
||||
<section id="boostbook.functions">
|
||||
<title>Functions</title>
|
||||
|
||||
<para>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; <xref linkend="boostbook.function.types"/>
|
||||
gives the elements for each C++ function type.</para>
|
||||
|
||||
<para>The behavior of functions in BoostBook is documenting using
|
||||
a style similar to that of the C++ standard, with clauses
|
||||
describing the requirements, effects, postconditions, exception
|
||||
behavior, and return values of functions. The names and uses of
|
||||
the XML elements for each clause type are given in <xref
|
||||
linkend="boostbook.function.clauses"/>.</para>
|
||||
|
||||
<para>The following example illustrates some constructors and a
|
||||
destructor for <classname>boost::any</classname>. We note that in
|
||||
each of the clauses from <xref
|
||||
linkend="boostbook.function.clauses"/> there is a (required!)
|
||||
<simpara> element containing the text for that clause. We
|
||||
also note that one of the constructors takes a single parameter
|
||||
whose name is "other" and whose type, <code>const any&</code>
|
||||
is contained in the <paramtype> element; any number of
|
||||
parameters may be specified in this way.</para>
|
||||
|
||||
<programlisting>
|
||||
<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>
|
||||
</programlisting>
|
||||
|
||||
<table id="boostbook.function.types">
|
||||
<title>BoostBook Function Types</title>
|
||||
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry><simpara>C++ Function</simpara></entry>
|
||||
<entry><simpara>BoostBook Element</simpara></entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><simpara>Constructor</simpara></entry>
|
||||
<entry><simpara><constructor></simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><simpara>Destructor</simpara></entry>
|
||||
<entry><simpara><destructor></simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><simpara>Copy assignment operator</simpara></entry>
|
||||
<entry><simpara><copy-assignment></simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><simpara>Member function</simpara></entry>
|
||||
<entry><simpara><method></simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><simpara>Free function</simpara></entry>
|
||||
<entry><simpara><function></simpara></entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<table id="boostbook.function.clauses">
|
||||
<title>BoostBook Function Semantics Clauses</title>
|
||||
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry><simpara>BoostBook element</simpara></entry>
|
||||
<entry><simpara>Description</simpara></entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><simpara><requires></simpara></entry>
|
||||
<entry><simpara>A set of requirements that must be met
|
||||
prior to execution of the function (a.k.a.,
|
||||
preconditions). If any of these requirements is not met
|
||||
and the function is executed, then the behavior is
|
||||
undefined.</simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><simpara><effects></simpara></entry>
|
||||
<entry><simpara>The effects of executing the function. For
|
||||
instance, this may include documenting changes in state,
|
||||
other functions executed, or output written to
|
||||
files.</simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><simpara><postconditions></simpara></entry>
|
||||
<entry><simpara>Conditions that are guaranteed to hold
|
||||
after execution of the function, assuming that all
|
||||
requirements have been met.</simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><simpara><returns></simpara></entry>
|
||||
<entry><simpara>A description of the value returned from
|
||||
the function.</simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><simpara><throws></simpara></entry>
|
||||
<entry><simpara>A description of the exceptions that may
|
||||
be thrown from this function.</simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><simpara><complexity></simpara></entry>
|
||||
<entry><simpara>The computational complexity of this
|
||||
function.</simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><simpara><notes></simpara></entry>
|
||||
<entry><simpara>Additional notes that clarify the behavior
|
||||
of the function.</simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><simpara><rationale></simpara></entry>
|
||||
<entry><simpara>Reasons for the current semantics,
|
||||
including an explanation of potential alternative
|
||||
semantics and reasons why the alternatives have not bee
|
||||
used.</simpara></entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</section>
|
||||
</section>
|
||||
Loading…
x
Reference in New Issue
Block a user