Breathe’s documentation¶

Breathe provides a bridge between the Sphinx and Doxygen documentation systems.

It is an easy way to include Doxygen information in a set of documentation generated by Sphinx. The aim is to produce an autodoc like support for people who enjoy using Sphinx but work with languages other than Python. The system relies on the Doxygen’s xml output.

Features¶

Simple setup - one doxygen config value, one Sphinx config value and one directive and you’ll be on your way.
High and low level directives - reference the whole project, just a class or just a function with different directives.
Support for multiple doxygen projects - set it up to be aware of different projects and reference them by name or path for each directive.
Allows embedded reStructuredText in doxygen markup - some extra doxygen aliases allow you to add \rst - \endrst blocks to your comments and have the contents interpreted as reStructuredText.
Basic support for Sphinx domains - Link to functions in the breathe output with a standard Sphinx domain reference.

Contents¶

Quick Start¶

For this quick start we assume the following prerequisites:

breathe was downloaded and extracted somewhere
doxygen was installed and doxygen output (XML format) was generated for the project that is to be documented (set GENERATE_XML tag to YES)

We assume the following paths:

documentation root path: /home/me/docproj/
breathe path: /home/me/docproj/ext/breathe/
doxygen xml output: /home/me/docproj/doxyxml/

The documentation path should contain a folder source containing the conf.py file. The doxygen xml output folder should contain the index.xml output file generated by doxygen.

The following steps are required to integrate breathe functionality:

Add the breathe path to your conf.py by adding the following line:
```
sys.path.append( "/home/me/docproj/ext/breathe/" )
```

Add breathe as an extension the line could look like this:

extensions = ['sphinx.ext.pngmath', 'sphinx.ext.todo', 'breathe' ]

Tell breathe about the projects:

breathe_projects = { "myproject": "/home/me/docproj/doxyxml/" }

Specify a default project:
```
breathe_default_project = "myproject"
```

Once this is done you may use the the following commands:

..doxygenindex::
..doxygenfunction::
..doxygenstruct::
..doxygenenum::
..doxygentypedef::
..doxygenclass::

to include documentation for different constructs. For each of these commands the the following directives may be specified:

project: Specifies which project, as defined in the breathe_projects config value, should be used for this directive. This overrides the default.
path: Directly specifies the path to the folder with the doxygen output. This overrides the project and default project.

Directives & Config Variables ¶

autodoxygenindex Directive Example¶

Working Example¶

This should work:

.. autodoxygenindex::
   :project: auto

With the following config value:

breathe_projects_source = {
     "auto" : ( "../examples/specific", ["auto_function.h", "auto_class.h"] )
     }

It produces this output:

class AutoClassTest

#include <auto_class.h>

class outside of namespace

Private Functions

void member(): non-namespaced class function

void anotherMember(): non-namespaced class other function

file auto_class.h

file auto_function.h

Functions

void autoFunction(): non-namespaced class function

void anotherAutoFunction(): non-namespaced class other function

dir /var/build/user_builds/breathe/checkouts/v2.0.0/examples

dir /var/build/user_builds/breathe/checkouts/v2.0.0/examples/specific

doxygenfunction Directive Example¶

Working Example¶

This should work:

.. doxygenfunction:: open
   :project: structcmd

It produces this output:

int open(const char * pathname, int flags)

Opens a file descriptor.

Detailed description.

Parameters

pathname -
The name of the descriptor.
flags -
Opening flags.

Failing Example¶

This intentionally fails:

.. doxygenfunction:: made_up_function
   :project: structcmd

It produces the following warning message:

Warning

doxygenfunction: Cannot find function “made_up_function” in doxygen xml output

doxygenstruct Directive Example¶

Example with Full Description¶

This should work:

.. doxygenstruct:: CoordStruct
   :project: restypedef

It produces this output:

struct CoordStruct

A coordinate pair.

Public Members

float x: The x coordinate

float y: The y coordinate

Example with Outline¶

This should work:

.. doxygenstruct:: CoordStruct
   :project: restypedef
   :outline:

It produces this output:

struct CoordStruct

Public Members

float x

float y

Example with Namespace¶

This should work:

.. doxygenstruct:: foo::ns::FooStruct
   :project: namespacefile

It produces this output:

struct foo::ns::FooStruct: #include <namespacefile.h>
Documentation here.

Failing Example¶

This intentionally fails:

.. doxygenstruct:: made_up_struct
   :project: restypedef

It produces the following warning message:

Warning

doxygenstruct: Cannot find struct “made_up_struct” in doxygen xml output

doxygenclass Directive Example¶

Example without Members¶

This should work:

.. doxygenclass:: Nutshell
   :project: nutshell

It produces this output:

class Nutshell

With a little bit of a elaboration, should you feel it necessary.

Example with Members¶

This should work:

.. doxygenclass:: Nutshell
   :project: nutshell
   :members:

It produces this output:

class Nutshell

With a little bit of a elaboration, should you feel it necessary.

Public Type

Tool enum

Our tool set.

The various tools we can opt to use to crack this particular nut

Values:

kHammer = = 0 -
What? It does the job.
kNutCrackers -
Boring.
kNinjaThrowingStars -
Stealthy.

Public Functions

Nutshell(): Nutshell constructor.

~Nutshell(): Nutshell destructor.

void crack(Tool tool)

Crack that shell with specified tool

Parameters

tool -
- the tool with which to crack the nut

bool isCracked()

Return: Whether or not the nut is cracked

Working Example with Specific Members¶

This should work:

.. doxygenclass:: Nutshell
   :project: nutshell
   :members: crack, isCracked

It produces this output:

class Nutshell

With a little bit of a elaboration, should you feel it necessary.

Public Functions

void crack(Tool tool)

Crack that shell with specified tool

Parameters

tool -
- the tool with which to crack the nut

bool isCracked()

Return: Whether or not the nut is cracked

Example as Outline¶

This should work:

.. doxygenclass:: Nutshell
   :project: nutshell
   :outline:
   :members:

It produces this output:

class Nutshell

Public Type

Tool enum

Values:

kHammer = = 0 -
kNutCrackers -
kNinjaThrowingStars -

Public Functions

Nutshell()

~Nutshell()

void crack(Tool tool)

bool isCracked()

Failing Example¶

This intentionally fails:

.. doxygenclass:: made_up_class
   :project: class
   :members:

It produces the following warning message:

Warning

doxygenclass: Cannot find class “made_up_class” in doxygen xml output

doxygenenum Directive Example¶

Working Example¶

This should work:

.. doxygenenum:: NodeType
   :project: tinyxml

It produces this output:

NodeType enum

The types of XML nodes supported by TinyXml.

(All the unsupported types are picked up by UNKNOWN.)

Values:

DOCUMENT -
ELEMENT -
COMMENT -
UNKNOWN -
TEXT -
DECLARATION -
TYPECOUNT -

Example with Namespace¶

This should work:

.. doxygenenum:: foo::ns::Letters
   :project: namespacefile

It produces this output:

Letters enum

Values:

A -
B -
C -

Failing Example¶

This intentionally fails:

.. doxygenenum:: made_up_enum
   :project: restypedef

It produces the following warning message:

Warning

doxygenenum: Cannot find enum “made_up_enum” in doxygen xml output

doxygentypedef Directive Example¶

Working Example¶

This should work:

.. doxygentypedef:: UINT32
   :project: structcmd

It produces this output:

typedef unsigned int UINT32

A type definition for a .

Details.

Example with Namespace¶

This should work:

.. doxygentypedef:: foo::ns::MyInt
   :project: namespacefile

It produces this output:

typedef int MyInt

Failing Example¶

This intentionally fails:

.. doxygentypedef:: made_up_typedef
   :project: restypedef

It produces the following warning message:

Warning

doxygentypedef: Cannot find typedef “made_up_typedef” in doxygen xml output

doxygenunion Directive Example¶

Working Example¶

This should work:

.. doxygenunion:: SeparateUnion
   :project: union

It produces this output:

union SeparateUnion

#include <union.h>

A union of two values.

Public Members

int size: The size of the thing.

float depth: How deep it is.

Example with Namespace¶

This should work:

.. doxygenunion:: foo::MyUnion
   :project: union

It produces this output:

union foo::MyUnion

#include <union.h>

A union of two values.

Public Members

int someInt: The int of it all.

float someFloat: The float side of things.

Failing Example¶

This intentionally fails:

.. doxygenunion:: made_up_union
   :project: union

It produces the following warning message:

Warning

doxygenunion: Cannot find union “made_up_union” in doxygen XML output for project “union” from directory: ../../examples/specific/union/xml/

doxygendefine Directive Example¶

Working Example¶

This should work:

.. doxygendefine:: WRITE_TREE_MISSING_OK
   :project: c_file

It produces this output:

WRITE_TREE_MISSING_OK: bitmasks to write_cache_as_tree flags

Failing Example¶

This intentionally fails:

.. doxygendefine:: MADEUPDEFINE
   :project: define

It produces the following warning message:

Warning

doxygendefine: Cannot find define “MADEUPDEFINE” in doxygen xml output for project “define” in directory: ../../examples/specific/define/xml

doxygenvariable Directive Example¶

Working Example¶

This should work:

.. doxygenvariable:: global_cache_tree
   :project: c_file

It produces this output:

struct cache_tree global_cache_tree: Shared cache tree instance.

Failing Example¶

This intentionally fails:

.. doxygenvariable:: made_up_variable
   :project: define

It produces the following warning message:

Warning

doxygenvariable: Cannot find variable “made_up_variable” in doxygen XML output for project “tinyxml” from directory: ../../examples/tinyxml/tinyxml/xml/

doxygenfile Directive Example¶

Example¶

This should work:

.. doxygenfile:: nutshell.h
   :project: nutshell

It produces this output:

An overly extended example of how to use breathe.

class Nutshell

#include <nutshell.h>

With a little bit of a elaboration, should you feel it necessary.

Public Type

Tool enum

Our tool set.

The various tools we can opt to use to crack this particular nut

Values:

kHammer = = 0 -
What? It does the job.
kNutCrackers -
Boring.
kNinjaThrowingStars -
Stealthy.

Public Functions

Nutshell(): Nutshell constructor.

~Nutshell(): Nutshell destructor.

void crack(Tool tool)

Crack that shell with specified tool

Parameters

tool -
- the tool with which to crack the nut

bool isCracked()

Return: Whether or not the nut is cracked

Private Members

bool m_isCracked: Our cracked state.

Example with Nested Namespaces¶

This should work:

.. doxygenfile:: namespacefile.h
   :project: namespacefile

It produces this output:

namespace foo

Functions

int baz(): This also appears.

class Bar

#include <namespacefile.h>

This appears in the documentation.

class InnerBar: This appears as a sub class.

namespace ns

More examples in a nested namespace.

Typedefs

typedef int MyInt

Enums

Letters enum

Values:

A -
B -
C -

struct FooStruct: #include <namespacefile.h>
Documentation here.

Example for Multiple Files¶

When there are multiple files with the same name in the project, you need to be more specific with the filename you provide. For example, in a project with the following two files:

/some/long/project/path/parser/Util.h
/some/long/project/path/finder/Util.h

You should specify:

.. doxygenfile:: parser/Util.h

.. doxygenfile:: finder/Util.h

To uniquely identify them.

Failing Example¶

This intentionally fails:

.. doxygenfile:: made_up_file.h
   :project: nutshell

It produces the following warning message:

Warning

Cannot find file “made_up_file.h” in doxygen xml output for project “nutshell” from directory: ../../examples/specific/nutshell/xml/

doxygengroup Directive Example¶

The doxygengroup directive renders the contents of the doxygen group as well as the group name and any documentation for the group itself.

Example¶

This should work:

.. doxygengroup:: mygroup
   :project: group

It produces this output:

group mygroup

This is the first group.

Functions

void groupedFunction(): This function is in MyGroup.

class GroupedClassTest

#include <group.h>

first class inside of namespace

Private Functions

void function(): namespaced class function

The directive also accepts a :content-only: option which changes the output to only include the content of the group and not the group name or description. So this:

.. doxygengroup:: mygroup
   :project: group
   :content-only:

Produces this output:

void groupedFunction(): This function is in MyGroup.

class GroupedClassTest

#include <group.h>

first class inside of namespace

Private Functions

void function(): namespaced class function

Failing Example¶

This intentionally fails:

.. doxygengroup:: madeupgroup
   :project: group

It produces the following warning message:

Warning

Cannot find file “madeupgroup” in doxygen xml output for project “group” from directory: ../../examples/specific/group/xml/

autodoxygenfile Directive Example¶

Working Example¶

This should work:

.. autodoxygenfile:: auto_class.h
   :source: auto

With the following config value:

breathe_projects_source = {
     "auto" : ( "../examples/specific", ["auto_class.h"] )
     }

It produces this output:

class AutoClassTest

#include <auto_class.h>

class outside of namespace

Private Functions

void member(): non-namespaced class function

void anotherMember(): non-namespaced class other function

Table of Contents

Directives & Config Variables
- Directives
- Config Values

Directives ¶

The available directives are shown below. In each case the project, path, no-link and outline options have the following meaning:

project

Specifies which project, as defined in the breathe_projects config value, should be used for this directive. This overrides the default project if one has been specified.

This is not used by the autodoxygenindex directive. Use source instead to specify the entry in the breathe_projects_source config value to use.

path

Directly specifies the path to the folder with the doxygen output. This overrides the project and default project if they have been specified.

This is not used by the autodoxygenindex directive. Use source-path instead to specify the root path to the sources files which are to be processed.

no-link

Instructs Breathe to not attempt to generate any document targets for the content generated by this particular directive.

This allows you to have your main reference listings somewhere with targets, but then to be able to sneak in repeat directives into other parts of the documentation to illustrate particular points without Sphinx getting confused what should be linked to by other references.

outline

Results in Breathe only outputting the raw code definitions without any additional description information.

If neither project nor path are provided on the directive then breathe will expect the breathe_default_project config value to be set.

doxygenindex ¶

This directive processes and produces output for everything described by the Doxygen xml output. It reads the index.xml file and process everything referenced by it.

.. doxygenindex::
   :project: ...
   :path: ...
   :outline:
   :no-link:

autodoxygenindex ¶

This directive performs a similar role to the doxygenindex directive except that it handles the doxygen xml generation for you. It uses the breathe_projects_source configuration dictionary to judge which code source files should have doxygen xml generated for them. The project directive option associates the directive with a particular project in the breathe_projects_source dictionary. All the files references by the entry in the breathe_projects_source will be included in the output.

Thank you to Scopatz for the idea and initial implementation.

.. autodoxygenindex::
   :project: ...
   :outline:
   :no-link:

Checkout the example to see it in action.

doxygenfunction ¶

This directive generates the appropriate output for a single function. The function name is required to be unique in the project.

.. doxygenfunction:: <function name>
   :project: ...
   :path: ...
   :outline:
   :no-link:

Checkout the example to see it in action.

doxygenstruct ¶

This directive generates the appropriate output for a single struct. The struct name is required to be unique in the project.

.. doxygenstruct:: <struct name>
   :project: ...
   :path: ...
   :outline:
   :no-link:

Checkout the example to see it in action.

doxygenenum ¶

This directive generates the appropriate output for a single enum. It behaves the same as the doxygenstruct directive.

.. doxygenenum:: <enum name>
   :project: ...
   :path: ...
   :outline:
   :no-link:

Checkout the example to see it in action.

doxygentypedef ¶

This directive generates the appropriate output for a single typedef. It behaves the same as the doxygenstruct directive.

.. doxygentypedef:: <typedef name>
   :project: ...
   :path: ...
   :outline:
   :no-link:

Checkout the example to see it in action.

doxygenunion ¶

This directive generates the appropriate output for a single union. It behaves the same as the doxygenstruct directive.

.. doxygenunion:: <union name>
   :project: ...
   :path: ...
   :outline:
   :no-link:

Checkout the example to see it in action.

doxygendefine ¶

This directive generates the appropriate output for a single preprocessor define. It behaves the same as the doxygenstruct directive.

.. doxygendefine:: <define name>
   :project: ...
   :path: ...
   :outline:
   :no-link:

Checkout the example to see it in action.

doxygenvariable ¶

This directive generates the appropriate output for a single variable. It behaves the same as the doxygenstruct directive.

.. doxygenvariable:: <variable name>
   :project: ...
   :path: ...
   :outline:
   :no-link:

Checkout the example to see it in action.

doxygenclass ¶

This directive generates the appropriate output for a single class. It takes the standard project, path, outline and no-link options and additionally members and sections option.

members

Designed to behavior in a similar manner to the members option for the autoclass directive that comes with the Sphinx autodoc extension.

If you do not specify this option you will not get any information about the class members, just the general class documentation. If you provide it without arguments, then Breathe adds all the public members and their documentation. If you specify it with comma separated arguments, then Breathe will treat the arguments as names of members and provide documentation for only those members that have been named.

The default behavior of adding the public members can be customized using the sections option.

sections

Designed to specialize the default behavior of the members option. You can specify a comma-separated list of sections to be included if no specific members are named. The list can accept wildcards. For instance, if you want to display the all protected and public members, functions, etc, then specify :sections: public*, protected*.

By default, breathe specifies public*.

Note that if your Doxygen project uses properties, these are excluded by default. Specify :sections: public*, property to include both public members and properties. (The section names correspond to the values of the kind attribute of the Doxygen XML sectiondef elements.)

.. doxygenclass:: <class name>
   :project: ...
   :path: ...
   :members: [...]
   :sections: [...]
   :outline:
   :no-link:

Checkout the example to see it in action.

doxygenfile ¶

This directive generates the appropriate output for the contents of a source file.

.. doxygenfile:: <filename>
   :project: ...
   :path: ...
   :no-link:

Checkout the example to see it in action.

autodoxygenfile ¶

This directive is this auto version of the doxygenfile directive above. It handles the doxygen xml generation for you like the other auto directives.

.. autodoxygenfile:: <filename>
   :project: ...
   :outline:
   :no-link:

Checkout the example to see it in action.

doxygengroup ¶

This directive generates the appropriate output for the contents of a doxygen group. A doxygen group can be declared with specific doxygen markup in the source comments as cover in the doxygen documentation.

It takes the standard project, path, outline and no-link options and additionally the content-only option.

content-only: If this flag is specified, then the directive does not output the name of the group or the group description and instead outputs the contents of the group. This can be useful if the groups are only used for organizational purposes and not to provide additional information.

.. doxygengroup:: <group name>
   :project: ...
   :path: ...
   :content-only:
   :no-link:

Checkout the example to see it in action.

Config Values ¶

breathe_projects¶: This should be a dictionary in which the keys are project names and the values are paths to the folder containing the doxygen output for that project.

breathe_default_project¶: This should match one of the keys in the breathe_projects dictionary and indicates which project should be used when the project is not specified on the directive.

breathe_domain_by_extension¶

Allows you to specify domains for particular files according to their extension.

For example:

breathe_domain_by_extension = {
        "h" : "cpp",
        }

breathe_domain_by_file_pattern¶

Allows you to specify domains for particular files by wildcard syntax. This is checked after breathe_domain_by_extension and so will override it when necessary.

For example:

breathe_domain_by_file_pattern = {
        "\*/alias.h" : "c",
        }

If you wanted all .h header files to be treated as being in the cpp domain you might use the breathe_domain_by_extension example above. But if you had one .h file that should be treated as being in the c domain then you can override as above.

breathe_projects_source¶

A dictionary in which the keys are project names and the values are a tuple of the directory and a list of file names of the source code for those projects that you would like to be automatically processed with doxygen. If you have some files in:

/some/long/path/to/myproject/file.c
/some/long/path/to/myproject/subfolder/otherfile.c

Then you can set:

breathe_projects_source = {
   "myprojectsource" :
       ( "/some/long/path/to/myproject", [ "file.c", "subfolder/otherfile.c" ] )
   }

Then your autodoxygenfile usage can look like this:

.. autodoxygenfile:: file.c
   :source: myprojectsource

The directory entry in the tuple can be an empty string if the entries in the list are full paths.

breathe_build_directory¶

In order to process the autodoxygenindex Breathe has to run doxygen to create the xml files for processing. This config value specifies the root directory that these files should be created in. By default, this is set to the parent directory of the doctrees output folder which is the normal build directory. You can change it with this setting if you have a custom set up.

Breathe will take the final value and append breathe/doxygen/<project name> to the path to minimize conflicts.

Supported Markups¶

All comments in your code must be formatted in a doxygen-compliant way so that doxygen can do its job. Doxygen provides support for formatting your text with tags, such as \b for adding bold text, this information appears in the xml output and Breathe attempts to reproduce it accurately.

In addition to this, is it possible to add reStructuredText into your comments within appropriately demarcated sections.

reStructuredText¶

Breathe supports reStructuredText within doxygen verbatim blocks which begin with the markup embed:rst. This means that a comment block like this:

/*!
Inserting additional reStructuredText information.
\verbatim embed:rst
.. note::

   This reStructuredText has been handled correctly.
\endverbatim
*/

Will be rendered as:

void rawVerbatim()

Inserting additional reStructuredText information.

Note

This reStructuredText has been handled correctly.

Handling Leading Asterisks¶

Note that doxygen captures all content in a verbatim block. This can be rather an annoyance if you use a leading-asterisk style of comment block such as the following:

/*!
 * Inserting additional reStructuredText information.
 *
 * \verbatim embed:rst
 *     Some example code::
 *
 *        int example(int x) {
 *            return x * 2;
 *        }
 * \endverbatim
 */

As the leading asterisks are captured in the verbatim block this will appear to be an incorrectly formatted bullet list. Due to the syntactical problems Sphinx will issue warnings and the block will render as:

void rawBadAsteriskVerbatim()

Inserting additional reStructuredText information.

Some example code:

int example(int x) {

return x * 2;

}

To prevent this, use an embed:rst:leading-asterisk tag:

/*!
 * Inserting additional reStructuredText information.
 *
 * \verbatim embed:rst:leading-asterisk
 *     Some example code::
 *
 *        int example(int x) {
 *            return x * 2;
 *        }
 * \endverbatim
 */

This will appropriately handle the leading asterisks and render as:

void rawLeadingAsteriskVerbatim()

Inserting additional reStructuredText information.

Some example code:

int example(int x) {
    return x   2;
}

Aliases¶

To make these blocks appears as more appropriate doxygen-like markup in your comments you can add the following aliases to your doxygen configuration file:

ALIASES = "rst=\verbatim embed:rst"
ALIASES += "endrst=\endverbatim"

And, if you use leading asterisks then perhaps:

ALIASES += "rststar=\verbatim embed:rst:leading-asterisk"
ALIASES += "endrststar=\endverbatim"

Which allow you to write comments like:

/*!
Inserting additional reStructuredText information.

\rst

This is some funky non-xml compliant text: <& !><

.. note::

   This reStructuredText has been handled correctly.
\endrst

This is just a standard verbatim block with code:

\verbatim
    child = 0;
    while( child = parent->IterateChildren( child ) )
\endverbatim

*/

Which will be rendered as:

void function()

Inserting additional reStructuredText information.

This is some funky non-XML compliant text: <& !><

Note

This reStructuredText has been handled correctly.

This is just a standard verbatim block with code:

    child = 0;
    while( child = parent->IterateChildren( child ) )

Domains¶

Breathe has some limited support for Sphinx domains. It tries to output targets that the Sphinx domain references expect. This should allow you to use Sphinx domain roles like :c:func:`foo` to link to output from Breathe.

The following targets are supported:

C & C++ functions
C++ classes

Class Example¶

Given the following Breathe directives:

.. doxygenclass:: testnamespace::NamespacedClassTest
   :path: ../../examples/specific/class/xml

Which create formatted output like:

class testnamespace::NamespacedClassTest

first class inside of namespace

We can refer to NamespacedClassTest using:

:cpp:class:`testnamespace::NamespacedClassTest`

which renders as testnamespace::NamespacedClassTest, or using:

:cpp:class:`another reference <testnamespace::NamespacedClassTest>`

which renders as: another reference.

Function Examples¶

Given the following Breathe directives:

.. doxygenfunction:: testnamespace::NamespacedClassTest::function
   :path: ../../examples/specific/class/xml

.. doxygenfunction:: frob_foos
   :path: ../../examples/specific/alias/xml

Which create formatted output like:

void function()

namespaced class function

void frob_foos(void * Frobs)

Foo frob routine.

bob this something else

Side Effects

Frobs any foos.

Return

Frobs any foos.

bob this something else

Side Effects

Frobs any foos.

Parameters

Frobs -
any foos.

We can refer to function using:

:cpp:func:`testnamespace::NamespacedClassTest::function()`

which renders as testnamespace::NamespacedClassTest::function(), or using:

:cpp:func:`another reference <testnamespace::NamespacedClassTest::function()>`

which renders as: another reference. Note the use of the cpp domain.

And we can refer to frob_foos using:

:c:func:`frob_foos()`

which renders as: frob_foos(), or using:

:c:func:`another reference <frob_foos()>`

which renders as: another reference. Note the use of the c domain.

Custom CSS¶

In order to help with the output styling in HTML, Breathe attaches some custom classes to parts of the document. There are three such classes:

breatheparameterlist

Used to keep the description of a parameter displayed inline with the parameter name. The Breathe docs use:

.breatheparameterlist li tt + p {
        display: inline;
}

breatheenumvalues

Used to keep the description of an enum displayed inline with the enum name. The Breathe docs use:

.breatheenumvalues li tt + p {
        display: inline;
}

Groups¶

Breathe has basic support for the grouping functionality that Doxygen provides.

Using the example from the Doxygen docs:

// Example from Doxygen documentation

/** A class. More details about the Test class */
class Test
{
  public:
    //@{
    /** Same documentation for both members. Details */
    void func1InGroup1();
    void func2InGroup1();
    //@}

    /** Function without group. Details. */
    void ungroupedFunction();
    void func1InCustomGroup();
  protected:
    void func2InCustomGroup();
};

void Test::func1InGroup1() {}
void Test::func2InGroup1() {}

/** @name Custom Group
 *  Description of custom group
 */
//@{
/** Function 2 in custom group. Details. */
void Test::func2InCustomGroup() {}
/** Function 1 in custom group. Details. */
void Test::func1InCustomGroup() {}
//@}

If we reference this with a directive, for example:

.. doxygenclass:: Test
   :project: userdefined
   :members:

It renders as:

class Test

A class.

More details about the Test class

Custom Group

Description of custom group

void func1InCustomGroup()

Function 1 in custom group.

Details.

void func2InCustomGroup()

Function 2 in custom group.

Details.

Unnamed Group

void func1InGroup1()

Same documentation for both members.

Details

void func2InGroup1()

Same documentation for both members.

Details

Public Functions

void ungroupedFunction()

Function without group.

Details.

Note

Any groups which are not named in the original source code will appear as Unnamed Group in the final output. This is different to Doxygen which will number the groups and so name them as Group1, Group2, Group3, etc.

Lists¶

Breathe has support for lists in the doxygen documentation. They are output as follows.

For unordered lists with list items prefixed with +

.. doxygenclass:: SimpleList_1
   :project: lists

It renders as:

class SimpleList_1

This is a list example.

Following is a list using ‘+’ for bullets:

One item.
Two items.
Three items.
Four.

And this is some more text.

Unordered lists with list items prefixed with - render as:

class SimpleList_2

This is a list example.

Following is a list using ‘-‘ for bullets:

One item.
Two items.
Three items.
Four.

And this is some more text.

Unordered lists with list items prefixed with * render as:

class SimpleList_3

This is a list example.

Following is a list using ‘*’ for bullets:

One item.
Two items.
Three items.
Four.

And this is some more text.

Unordered lists defined using HTML tags <ul><li> render as:

class SimpleList_6

This is a list example.

Following is an unordered list using ‘HTML’ tags:

One item.
Two items.
Three items.
Four.

And this is some more text.

Auto-numbered lists with list items prefixed with -# render as:

class SimpleList_4

This is a list example.

Following is an auto-numbered list:

One item.
Two items.
Three items.
Four.

And this is some more text.

Numbered lists with list items prefixed with Arabic numerals 1. 2. ... render as:

class SimpleList_5

This is a list example.

Following is a numbered list:

One item.
Two items.
Three items.
Four.

And this is some more text.

Note

Numbered lists support for the moment only Arabic numerals.

Nested lists are supported in all combinations, as long as they are valid doxygen markup. Below are a couple of examples of different nested lists documentation and their corresponding breathe output.

Documentation looking like this:

/**
 *      \file nested_list_1.h
 *      Example of nested lists in documentation.
 */

/**
 *  A list of events:
 *    - mouse events
 *         -# mouse move event
 *         -# mouse click event\n
 *            More info about the click event.
 *         -# mouse double click event
 *    - keyboard events
 *         1. key down event
 *         2. key up event
 *
 *  More text here.
 */
class NestedLists_1
{
};

renders as:

class NestedLists_1

A list of events:

mouse events
1. mouse move event
2. mouse click event More info about the click event.
3. mouse double click event
keyboard events
1. key down event
2. key up event

More text here.

Documentation looking like this:

/**
 *      \file nested_list_2.h
 *      Example of nested list in documentation.
 */

/**
 * Text before the list
 * - list item 1
 *   - sub item 1
 *     - sub sub item 1
 *     - sub sub item 2
 *     .
 *     The dot above ends the sub sub item list.
 *
 *     More text for the first sub item
 *   .
 *   The dot above ends the first sub item.
 *
 *   More text for the first list item
 *   - sub item 2
 *   - sub item 3
 * - list item 2
 * .
 * More text in the same paragraph.
 *
 * More text in a new paragraph.
 */
class NestedLists_2
{
};

renders as:

class NestedLists_2

Text before the list.

list item 1
- sub item 1
  - sub sub item 1
  - sub sub item 2
  The dot above ends the sub sub item list.
  
  More text for the first sub item
The dot above ends the first sub item.

More text for the first list item
- sub item 2
- sub item 3
list item 2

More text in the same paragraph.

More text in a new paragraph.

Documentation looking like this:

/**
 *      \file nested_list_3.h
 *      Example of nested lists in documentation.
 */

/*!
 *  A list of events:
 *  <ul>
 *  <li> mouse events
 *     <ol>
 *     <li>mouse move event
 *     <li>mouse click event<br>
 *         More info about the click event.
 *     <li>mouse double click event
 *     </ol>
 *  <li> keyboard events
 *     <ol>
 *     <li>key down event
 *     <li>key up event
 *     </ol>
 *  </ul>
 *  More text here.
 */
 class NestedLists_3
{
};

renders as:

class NestedLists_3

A list of events:

mouse events
1. mouse move event
2. mouse click event More info about the click event.
3. mouse double click event
keyboard events
1. key down event
2. key up event

More text here.

Documentation looking like this:

/**
 *      \file nested_list_4.h
 *      Example of nested lists in documentation.
 */

/**
 *  A list of events:
 *    1. mouse events
 *        -# mouse move event
 *            1. swipe event
 *            2. circle event
 *            3. wave event
 *        -# mouse click event\n
 *            More info about the click event.
 *        -# mouse double click event
 *    2. keyboard events
 *        -# key down event
 *        -# key up event
 *    3. touch events
 *        -# pinch event
 *        -# swipe event
 *  More text here.
 */
class NestedLists_4
{
};

renders as:

class NestedLists_4

A list of events:

mouse events
1. mouse move event
  1. swipe event
  2. circle event
  3. wave event
2. mouse click event More info about the click event.
3. mouse double click event
keyboard events
1. key down event
2. key up event
touch events
1. pinch event
2. swipe event More text here.

Documentation looking like this:

/**
 *      \file nested_list_4.h
 *      Example of nested lists in documentation.
 */

/**
 *  A deeply nested list of events:
 *    1. mouse events
 *        -# mouse move event
 *            1. swipe event
 *              -# swipe left
 *                  1. swipe left residual (it's nonsense)
 *                  2. more nonsense
 *                  3. even more nonsense
 *                      -# deep even more nonsense
 *                  4. even even more nonsense
 *              -# swipe right
 *            2. circle event
 *            3. wave event
 *        -# mouse click event\n
 *            More info about the click event.
 *        -# mouse double click event
 *    2. keyboard events
 *        -# key down event
 *        -# key up event
 *    3. touch events
 *        -# pinch event
 *        -# swipe event
 *  More text here.
 */
class NestedLists_5
{
};

renders as:

class NestedLists_5

A deeply nested list of events:

mouse events
1. mouse move event
  1. swipe event
    1. swipe left
      1. swipe left residual (it’s nonsense)
      2. more nonsense
      3. even more nonsense
        
        deep even more nonsense
      4. even even more nonsense
    2. swipe right
  2. circle event
  3. wave event
2. mouse click event More info about the click event.
3. mouse double click event
keyboard events
1. key down event
2. key up event
touch events
1. pinch event
2. swipe event More text here.

Template¶

Breathe has support for class and function templates. They are output as follows. For a class with a single template parameter:

.. doxygenclass:: templateclass
   :project: template_class
   :members:

It renders as:

template <typename T> class templateclass

a class with a template parameter

Templates

T -
this is the template parameter

Public Functions

templateclass(): default constructor

templateclass(T const & m)

constructor with template argument

Parameters

m -
the argument

T method(T const & t)

member accepting template argument and returning template argument

Return

returns value of type T

Parameters

t -
argument of type T

With multiple template parameters it renders as:

template <typename T, typename U, int N> class anothertemplateclass

a class with three template parameters

Templates

T -
this is the first template parameter
U -
this is the second template parameter
N -
this is the third template parameter, it is a non-type parameter

Public Functions

anothertemplateclass(): default constructor

anothertemplateclass(T const & m1, U const & m2)

constructor with two template argument

Parameters

m1 -
first argument
m2 -
second argument

U method(T const & t)

member accepting template argument and returning template argument

Return

returns value of type U

Parameters

t -
argument

A function with single template parameter renders as:

template <typename T> T function1(T arg1)

a function with one template arguments

Return

return value of type T

Templates

T -
this is the template parameter

Parameters

arg1 -
argument of type T

With multiple template parameters it renders as:

template <typename T, typename U, int N> T function2(T arg1, U arg2)

a function with three template arguments

Return

return value of type T

Templates

T -
this is the first template parameter
U -
this is the second template parameter
N -
this is the third template parameter, it is a non-type parameter

Parameters

arg1 -
first argument of type T
arg2 -
second argument of type U

Latex Math¶

Breathe has basic support for latex math markup in the doxygen comments. A class with a comment like:

/**
 * @brief A class
 *
 * A inline formula: \f$ f(x) = a + b \f$
 *
 * A display style formula:
 * @f[
 * \int_a^b f(x) dx = F(b) - F(a)
 * @f]
 *
 * A specific environment formula:
 * \f{equation}{
 * \begin{array}{cc}
 * a & b \\
 * c & d
 * \end{array}
 * \f}
 */
class MathHelper
{
public:
  MathHelper() {}
  ~MathHelper() {}
}

Will be renderer as:

class MathHelper

A class.

A inline formula: \( f(x) = a + b \)

A display style formula:

\[ \int_a^b f(x) dx = F(b) - F(a) \]

A specific environment formula:

\[\begin{split}\begin{equation} \begin{array}{cc} a & b \\ c & d \end{array} \end{equation}\end{split}\]

Public Functions

MathHelper()

~MathHelper()

Without any additional configuration except for including a math extension in the Sphinx conf.py:

extensions = [ "breathe", "sphinx.ext.mathjax" ]

The specific environment formula fails when using sphinx.ext.pngmath so more work is needed.

Implementation¶

Breathe uses a internal reStructuredText node provided by sphinx.ext.mathbase which is then picked up and rendered by the extension chosen in the conf.py. It does not pass any additional options through to the node, so settings like label and nowrap are currently not supported.

Credits¶

Thank you to dazzlezhang for providing examples and a full run down of necessary details. It made the implementation much easier.

Running on Read the Docs¶

Read the Docs is an excellent site for hosting project documentation. It provides hooks into common project hosting sites like Github & Bitbucket and can rebuild your documentation automatically whenever you push new code.

The site is designed for documentation written with Sphinx and supports Sphinx extensions via a correctly configured setup.py file.

As Breathe is a Sphinx extension you can use it on Read the Docs. However, as Breathe requires doxygen XML files, some additional configuration is required.

Doxygen Support¶

Read the Docs do not explicitly support doxygen however they have had requests for it to be supported and it is currently installed on their build servers.

Generating Doxygen XML Files¶

We assume that you are not checking your doxygen XML files into your source control system and so you will need to generate them on the Read the Docs server before Sphinx starts processing your documentation.

One simple way of achieving this is to add the following code to your conf.py file:

import subprocess, os

read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'

if read_the_docs_build:

    subprocess.call('cd ../doxygen; doxygen', shell=True)

The first line uses the READTHEDOCS environment variable to determine whether or not we are building on the Read the Docs servers. Read the Docs set this environment variable specifically for this purpose.

Then, if we are in a Read the Docs build, execute a simple shell command to build the doxygen xml for your project. This is a very simple example; the command will be determined by your project set up but something like this works for the Breathe documentation.

As this is then executed right at the start of the sphinx-build process then all your doxygen XML files will be in place for the build.

A More Involved Setup¶

If you’d rather do something more involved then you can run doxygen as part of a builder-inited event hook which you can install from your conf.py file by adding a setup function as shown below.

This is an approximation of the code that Breathe has in its conf.py in order to run doxygen on the Read the Docs server.

import subprocess, sys

def run_doxygen(folder):
    """Run the doxygen make command in the designated folder"""

    try:
        retcode = subprocess.call("cd %s; make" % folder, shell=True)
        if retcode < 0:
            sys.stderr.write("doxygen terminated by signal %s" % (-retcode))
    except OSError as e:
        sys.stderr.write("doxygen execution failed: %s" % e)


def generate_doxygen_xml(app):
    """Run the doxygen make commands if we're on the ReadTheDocs server"""

    read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'

    if read_the_docs_build:

        run_doxygen("../../examples/doxygen")
        run_doxygen("../../examples/specific")
        run_doxygen("../../examples/tinyxml")


def setup(app):

    # Add hook for building doxygen xml when needed
    app.connect("builder-inited", generate_doxygen_xml)

Contributing to Breathe¶

There are four main ways you might consider contributing to Breathe.

Give It A Go¶

...and let me know! Firstly, the more people using it the better, but more than that, hearing about the project being put to use is a great motivator for the developer, namely me.

Report Bugs & Suggest Features¶

Embarrassingly I don’t get to use Breathe that much in my general work, so it doesn’t really get pushed beyond the test code we have here in the repository.

If you use it and find issues with it, minor or major, please let me know and if possible provide some detail so I can reproduce it.

With the help of those who have posted issues on the github issue tracker we’ve managed to track down and improve some of the less obvious (and some more obvious!) parts of Breathe that weren’t working properly.

Improve the Documentation¶

I’ve made an effort to document Breathe so it is usable, but I have a twisted perspective on the whole thing as I made it.

I’ve already had some help with the documentation, which was greatly appreciated, but if you managed to get it working and find that the documentation could have been clearer in parts, let me know or write up a paragraph or two that would have helped you when you were trying it.

Fork It! And Improve the Code¶

If you find a bug, quite like Python and have some time, then grab a copy of the code and have a go at fixing it. Nothing motivates me quite like other people caring enough to put a bit of time into working on it. The contributions we’ve had this way have been great and much appreciated.

If you want to help out, take a look at the code guide to see how it is all structured and works.

How It Works¶

There are three main sections to Breathe: parser, finders and renderers. Briefly:

parser

Responsible for reading the doxygen xml output and creating objects representing the data. Found in breathe.parser.

finders

Responsible for finding reference objects within the output from the parser. Found in breathe.finder.

renderers

Responsible for producing reStructuredText nodes to represent the objects that the finders have found. The renderers generally descend through the object hierarchies rendering the objects, their children, their children’s children and so on. Found in breathe.renderer.

Parser¶

The parsers job is to parse the doxygen xml output and create a hierarchy of Python objects to represent the xml data.

Doxygen XML Output¶

The xml output from doxygen comes in multiple files. There is always an index.xml file which is a central reference point and contains a list of all the other files that have been generated by doxygen and an indication of what they contain.

For example, in examples/doxygen/func/xml directory, the index.xml file contains:

<?xml version='1.0' encoding='UTF-8' standalone='no'?>
<doxygenindex xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="index.xsd" version="1.7.2">
  <compound refid="class_test" kind="class"><name>Test</name>
    <member refid="class_test_1a45b6a232a4499f8ce37062eab5451570" kind="function"><name>member</name></member>
  </compound>
  <compound refid="func_8h" kind="file"><name>func.h</name>
  </compound>
</doxygenindex>

This suggests there is additional information about a class called Test which has a function called member. Additionally there is some more information about a file called func.h.

Now, the refid attribute on the compound xml nodes gives an indication of where the additional information can be found. So for the Test class, we should look in class_test.xml, which we get by simply appending .xml to the refid value, and for the func.h file we should look in func_8h.xml.

So the index.xml file is unique in its role and has its own structure which is defined in the index.xsd file which you will also find in the same directory. All the other files, the ones referenced by the index.xml file, follow another structure. This is described in compound.xsd file so we call these other files compound files. These are generally longer than the index.xml file and contain all the specific information you might expect from doxygen, including any documentation you added to your code as doxygen markup.

Have a look at examples/doxygen/func/xml/class_test.xml for a fairly short example.

Doing the Parsing¶

To get things up and running quickly, I have used the generateDS project to help create classes to parse the doxygen xml output. The script automatically creates the compound.py, compoundsuper.py, index.py and indexsuper.py files that you can see inside breathe/parser/doxygen.

So what is the difference between index.py and indexsuper.py, and compound.py and compoundsuper.py? These files allow us to separate the bulk of the automatically generated code from the code changes we might want to make. There are a large number of classes in the ...super.py files and each one has a basic derived class in the corresponding non-super files.

It is designed so that all the hard work done by the generated code is done in the ...super.py files and if we need to make changes we can do them in the derived classes in the non-super files and if we ever need to regenerate the code, we only regenerate the ...super.py files and so we don’t lose our changes in the process.

The end result is that for the parsing, we have written relatively little code, but have a large amount automatically generated for us. This has only been done once and it seems relatively unlikely that we’ll do it again. The entry points to the parsing code is the parse functions at the bottom of the breathe.parser.doxygen.compound and breathe.parser.doxygen.index.

I have never really examined the details of the parsing but you can see that there is a class for each node type you are likely to find in the xml files. I say “node type” instead of just “node” because different nodes can share the same type and there is one class per type. For example, there are detaileddescription nodes and briefdescription nodes which are both of type descriptionType. If we look in breathe.parser.doxygen.compoundsuper we see a descriptionType class and in breathe.parser.doxygen.compound we see a descriptionTypeSub class which is derived from descriptionType.

Our Changes¶

You’ll notice there are some classes in the non-super files that have some additional code in them. This tends to be adjusting the buildChildren member function in the derived class to extend or override the one in the automatically generated base class.

We have to do this sometimes as it seems the original code we generated with generateDS fails to construct the children of some classes. The generateDS scripts uses the descriptions in the .xsd files to determine what classes to generate and what nodes can be the children of other nodes. It is possible that the doxygen .xsd files contain levels of abstraction that the generateDS project did not cope with at the time I used it. It is possible that newer versions would handle it better but for the moment I’m content updating the derived classes to handle the cases I see missing.

Finders¶

The finder classes have a relatively small but important job of finding objects in the hierarchy generated by the parsers. For example, when a user specifies a particular class for the doxygenclass directive, we use the finder classes to go and find the object corresponding to that class.

In fact, if you look closely, it is the finders that use the parser entry points to parse the xml and then find the objects. The finders also use Matcher objects to actually figure out if they have found what they are looking for.

In the simplest case, the finder only has to find the root of the hierarchy for the doxygenindex directive. In the other cases, the finder is given a MatcherStack and the level of the hierarchy it should be aiming for. The MatcherStack is what is sounds like, a stack of Matcher objects which are designed to match at different levels of the hierarchy,

More Details, Please¶

So initially, we create a finder to look at the root of the hierarchy: the doxygenTypeSub node. That finder, handily called DoxygenTypeSubItemFinder (you’ll notice a lot of that) looks through all the child compound nodes of the doxygenTypeSub node and tries a compound-level match against each of them and if something matches it creates a CompoundTypeSubItemFinder to look further.

In turn, that checks each of its member child nodes with a member-level match and if it finds one it creates a MemberTypeSubItemFinder (see the pattern?) and that does another check. The interesting part is, if that is successful, the CompoundTypeSubItemFinder finds the corresponding xml file that has more information in it (remember refid + .xml?) and parses that and creates another finder to start looking in there. This time it is a DoxygenTypeSubItemFinder from the breathe.finder.doxygen.compound module. And the search goes on until we find an object to return for rendering.

If the CompoundTypeSubItemFinder fails to find any deeper levels to match against then it returns itself as it must be the target we’re interested in.

As stated, the job of the finder is to find a single node for the renderers to starting rendering to reStructuredText. That is all the finder does.

Renderers¶

Finally, the bit that really does something we care about. Rendering is the art of turning whatever object we’ve found in the hierarchy into reStructuredText nodes. This almost invariably means most of its children as well.

Much like with the finder classes, we start off creating a renderer for a particular parser object and then it looks at its children and uses the renderer factory to create appropriate renderers for those objects and tells them to render and they look at their object’s children and create appropriate renderers for those and so on and so forth.

The node we start at is determined by the finder and ultimately by the user. The whole process is kicked off by the Builder class, though it doesn’t really do much. The aim of the renderers is to return a list of reStructuredText nodes which is passed back to Sphinx to render into whatever you’re final output format is.

There are two complicated bits here. All the different renderers and all the different reStructuredText nodes.

Different Renderers¶

Just like with the parsers, there is one renderer per node type. In fact there is one renderer class per parser class and they are named almost the same and are designed to match up. The renderers look at the data on the instance of the corresponding parser class that they have been given and grab the interesting bits and return reStructuredText nodes.

For reference on what there is to render, you can look at the parser class definitions or at the raw xml to see what attributes there are to render. Sometimes if something isn’t appearing in the final output, it is because the renderer isn’t returning an reStructuredText representation of it so the rendering code needs to be updated, and sometimes it is because the parser classes are not picking it up properly so both the parser and the renderer code needs to be updated.

Given a little bit of time, you get used to chasing through the xml nodes, the parser classes and the corresponding renderers to figure out where all the information is ending up.

reStructuredText Nodes¶

We use the reStructuredText API as provided by the fabulous docutils project and extended by Sphinx itself. For the most part, they are fairly straight forward and they are certainly well named.

Unfortunately there are a lot of nodes and only certain ways of combining them. It is also not always clear what arguments their constructs take. Whilst I’m sure it would be possible to figure it out with time and the appropriate source code, the use of them is not something I’ve found very well documented and my code largely operates on a basis of trial and error.

One day I’m sure I’ll be enlightened, until then expect fairly naive code.

Test Pages¶

Doxygen Test Suite¶

Class¶

class Test

#include “inc/class.h”

This is a test class.

Some details about the Test class

file class.h

Define¶

file define.h

testing defines

This is to test the documentation of defines.

Defines

ABS(x): Computes the absolute value of its argument x.

MAX(x, y): Computes the maximum of x and y.

MIN(x, y): Computes the minimum of x and y.

NOARGS: Define with no arguments

Enum¶

class Test

#include <enum.h>

The class description.

Public Type

TEnum enum

A description of the enum type.

Values:

Val1 -
The description of the first enum value.
Val2 -

AnotherEnum enum

Another enum, with inline docs

Values:

V1 -
value 1
V2 -
value 2

file enum.h

File¶

file file.h

A brief file description.

A more elaborated file description.

Variables

int globalValue

A global integer value.

More details about this value.

Func¶

class Test

#include <func.h>

Test class.

Details about Test.

Public Functions

const char * member(char c, int n)

A member function.

Return

a character pointer.

Parameters

c -
a character.
n -
an integer.

Exceptions

std::out_of_range -
parameter is out of range.

file func.h

Page¶

file page.doc

page page1: Leading text.

page page2: Even more info.

Relates¶

class String

A String class.

Friends

friend int strcmp: Compares two strings.

file relates.cpp

Functions

int strcmp(const String & s1, const String & s2): Compares two strings.

Author¶

class WindowsNT

Windows Nice Try.

Author

Bill Gates

Several species of small furry animals gathered together in a cave and grooving with a picture.

Version

4.0

Date

1996-1998

file author.cpp

page bug

Par¶

class Test

Normal text.

More normal text.

User defined paragraph:: Contents of the paragraph.
: New paragraph under the same heading.
Note: This note consists of two paragraphs. This is the first paragraph.
: And this is the second paragraph.

file par.cpp

Overload¶

class Test

A short description.

More text.

Public Functions

void drawRect(int x, int y, int w, int h): This command draws a rectangle with a left upper corner at ( x , y ), width w and height h.

void drawRect(const Rect & r): This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

file overload.cpp

Example¶

class Test

A Test class.

More details about this class.

Public Functions

void example()

An example member function.

More details about this function.

file example.cpp

example example_test.cpp

This is an example of how to use the Test class.More details about this example.

void main()
{
  Test t;
  t.example();
}

Include¶

class Test

A test class.

Public Functions

void example(): a member function

file include.cpp

page example

Our main function starts like this: First we create a object t of the Test class. Then we call the example member function After that our little test routine ends.

void main()
{

  Test t;

  t.example();

QtStyle¶

class Test

A test class.

A more elaborate class description.

Public Type

TEnum enum

An enum.

More detailed enum description.

Values:

TVal1 -
Enum value TVal1.
TVal2 -
Enum value TVal2.
TVal3 -
Enum value TVal3.

Public Functions

Test()

A constructor.

A more elaborate description of the constructor.

~Test()

A destructor.

A more elaborate description of the destructor.

int testMe(int a, const char * s)

A normal member taking two arguments and returning an integer value.

Return

The test results

See

Test(), ~Test(), testMeToo() and publicVar()

Parameters

a -
an integer argument.
s -
a constant character pointer.

void testMeToo(char c1, char c2)

A pure virtual member.

See

testMe()

Parameters

c1 -
the first argument.
c2 -
the second argument.

Public Members

enum Test::TEnum * enumPtr

Enum pointer.

Details.

enum Test::TEnum enumVar

Enum variable.

Details.

int publicVar

A public variable.

Details.

int(* handler)(int a, int b)

A function variable.

Details.

file qtstyle.cpp

JdStyle¶

class Test

A test class.

A more elaborate class description.

Public Type

TEnum enum

An enum.

More detailed enum description.

Values:

TVal1 -
enum value TVal1.
TVal2 -
enum value TVal2.
TVal3 -
enum value TVal3.

Public Functions

Test()

A constructor.

A more elaborate description of the constructor.

~Test()

A destructor.

A more elaborate description of the destructor.

int testMe(int a, const char * s)

a normal member taking two arguments and returning an integer value.

See

Return

The test results

Parameters

a -
an integer argument.
s -
a constant character pointer.

void testMeToo(char c1, char c2)

A pure virtual member.

See

testMe()

Parameters

c1 -
the first argument.
c2 -
the second argument.

Public Members

enum Test::TEnum * enumPtr

enum pointer.

Details.

enum Test::TEnum enumVar

enum variable.

Details.

int publicVar

a public variable.

Details.

int(* handler)(int a, int b)

a function variable.

Details.

file jdstyle.cpp

StructCmd¶

file structcmd.h

A Documented file.

Details.

Defines

MAX(a, b)

A macro that returns the maximum of a and b.

Details.

Typedefs

typedef unsigned int UINT32

A type definition for a .

Details.

Functions

int open(const char * pathname, int flags)

Opens a file descriptor.

Detailed description.

Parameters

pathname -
The name of the descriptor.
flags -
Opening flags.

int close(int fd)

Closes the file descriptor fd.

Parameters

fd -
The descriptor to close.

size_t write(int fd, const char * buf, size_t count)

Writes count bytes from buf to the file descriptor fd.

Parameters

fd -
The descriptor to write to.
buf -
The data buffer to write.
count -
The number of bytes to write.

int read(int fd, char * buf, size_t count)

Read bytes from a file descriptor.

Parameters

fd -
The descriptor to read from.
buf -
The buffer to read into.
count -
The number of bytes to read.

Variables

int errno

Contains the last error code.

Warning: Not thread safe!

Autolink¶

class Test

Since this documentation block belongs to the class Test no link to Test is generated.

Two ways to link to a constructor are: Test and Test().

Links to the destructor are: ~Test and ~Test().

A link to a member in this class: member().

More specific links to the each of the overloaded members: member(int) and member(int,int).

A link to the variable var.

A link to the global typedef B.

A link to the global enumeration type GlobEnum.

A link to the define ABS(x).

A link to a variable using another text as a link.

A link to the enumeration type EType.

A link to some enumeration values: Val1 and GVal1.

And last but not least a link to a file: autolink.cpp.

See: Inside a see also section any word is checked, so EType, Val1, GVal1, ~Test and member will be replaced by links in HTML.

Public Type

EType enum

An enum type.

More details

Values:

Val1 -
enum value 1
Val2 -
enum value 2

Public Functions

Test()

constructor

details.

~Test()

destructor

details.

void member(int)

A member function.

Details.

void member(int, int)

An overloaded member function.

Details

Protected Attributes

int var: A member variable.

file autolink.cpp

Testing automatic link generation.

A link to a member of the Test class: Test::member,

More specific links to the each of the overloaded members: Test::member(int) and Test::member(int,int)

A link to a protected member variable of Test: Test::var,

A link to the global enumeration type GlobEnum.

A link to the define ABS(x).

A link to the destructor of the Test class: Test::~Test,

A link to the typedef B.

A link to the enumeration type Test::EType

A link to some enumeration values Test::Val1 and GVal2

Defines

ABS(x): A macro definition.

Typedefs

typedef Test B: A type definition.

Enums

GlobEnum enum

A global enum.

Values:

GVal1 -
global enum value 1
GVal2 -
global enum value 2

Variables

int globVar: A global variable.

ResTypeDef¶

struct CoordStruct

A coordinate pair.

Public Members

float x: The x coordinate

float y: The y coordinate

file restypedef.cpp

An example of resolving typedefs.

Typedefs

typedef CoordStruct Coord: Creates a type name for CoordStruct

Functions

Coord add(Coord c1, Coord c2): This function returns the addition of c1 and c2, i.e: (c1.x+c2.x,c1.y+c2.y)

AfterDoc¶

class Test

#include <afterdoc.h>

A test class

Public Type

EnumType enum

An enum type.

The documentation block cannot be put after the enum!

Values:

EVal1 -
enum value 1
EVal2 -
enum value 2

Public Functions

void member(): a member function.

Protected Attributes

int value: an integer value

file afterdoc.h

Template¶

template <class T, int i = 100> class Test

A template class

Public Functions

Test(): The constructor of the template class

Test(const Test & t): The copy constructor

template <class T> class Test< T * >

A partial template specialization

Public Functions

Test(): The constructor of the partial specialization

template <> class Test< void *, 200 >

complete specialization

Public Functions

Test(): The constructor of the specialization

file templ.cpp

Tag¶

class Tag

A class that is inherited from the external class Test.

Public Functions

void example(): an overloaded member.

file tag.cpp

Group¶

class C1: class C1 in group 1

class C2: class C2 in group 1

class C3: class C3 in group 2

class C4: class C4 in group 2

class C5: class C5 in the third group.

namespace N1

namespace N1 is in four groups

Also see This is another section in group 5

See: The first group, The Second Group, The Third Group, The Fourth Group

file group.cpp

this file in group 3

Functions

void func(): function in group 1

void func2(): another function in group 1

void func3(): yet another function in group 1

group group1

This is the first group.

Diagrams¶

class A

#include <diagrams_a.h>

Public Members

A * m_self

class B

#include <diagrams_b.h>

Public Members

A * m_a

class C

#include <diagrams_c.h>

Public Members

D * m_d

class D

#include <diagrams_d.h>

Public Members

C m_c

class E: #include <diagrams_e.h>

file diagrams_a.h

file diagrams_b.h

file diagrams_c.h: #include “diagrams_c.h”

file diagrams_d.h: #include “diagrams_a.h”#include “diagrams_b.h”

file diagrams_e.h: #include “diagrams_d.h”

Memgrp¶

class Test

A class.

Details

Group2

Description of group 2.

void func1InGroup2()

Function 1 in group 2.

Details.

void func2InGroup2()

Function 2 in group 2.

Details.

Unnamed Group

void func1InGroup1()

Same documentation for both members.

Details

void func2InGroup1()

Same documentation for both members.

Details

Public Functions

void ungroupedFunction()

Function without group.

Details.

file memgrp.cpp

docs for this file

Unnamed Group

A: one description for all members of this group (because DISTRIBUTE_GROUP_DOC is YES in the config file)

B: one description for all members of this group (because DISTRIBUTE_GROUP_DOC is YES in the config file)

void glob_func(): one description for all members of this group (because DISTRIBUTE_GROUP_DOC is YES in the config file)

Docstring¶

class docstring::PyClass

Documentation for a class.

More details.

Public Functions

def __init__()

The constructor.

def PyMethod()

Documentation for a method.

Private Members

_memVar

namespace docstring

@package docstring
Documentation for this module.

More details.

Functions

def func()

Documentation for a function.

More details.

file docstring.py

PyExample¶

class pyexample::PyClass

Documentation for a class.

More details.

Public Functions

def __init__(): The constructor.

def PyMethod()

Documentation for a method.

Parameters

self -
The object pointer.

Public Static Attributes

int classVar: A class variable.

Private Members

_memVar: a member variable

namespace pyexample

Documentation for this module.

More details.

Functions

def func()

Documentation for a function.

More details.

file pyexample.py

Mux¶

class mux_using_with::behavior

Architecture definition of the MUX.

More details about this mux element.

class mux_using_with

Mux entity brief description.

Public Members

in din_0std_logic

Mux first input.

Detailed description of this mux design element.

in din_1std_logic: Mux Second input.

in selstd_logic: Select input.

out mux_outstd_logic: Mux output.

_library_ ieeeieee: Use standard library.

_use_ ieee.std_logic_1164.allieee.std_logic_1164.all: Use logic elements.

file mux.vhdl: 2:1 Mux using with-select

Manual¶

struct Car

Car type.

Car class.

Protected Attributes

Vehicle base: Base class.

struct Object

Object type.

Base object class.

Public Functions

Object * objRef(Object * obj): Increments object reference count by one.

Object * objUnref(Object * obj): Decrements object reference count by one.

Private Members

int ref: Reference count.

struct Truck

Truck type.

Truck class.

Protected Attributes

Vehicle base: Base class.

struct Vehicle

Vehicle type.

Vehicle class.

Public Functions

void vehicleStart(Vehicle * obj): Starts the vehicle.

void vehicleStop(Vehicle * obj): Stops the vehicle.

Protected Attributes

Object base: Base class.

file manual.c

Functions

int main(void)

Main function.

Ref vehicleStart(), objRef(), objUnref().

TinyXML Test Suite¶

struct TiXmlBase::Entity

Public Members

const char * str

unsigned int strLength

char chr

class TiXmlAttribute

#include <tinyxml.h>

An attribute is a name-value pair.

Elements have an arbitrary number of attributes, each with a unique name.

Note: The attributes are not TiXmlNodes, since they are not part of the tinyXML document object model. There are other suggested ways to look at this problem.

Public Functions

TiXmlAttribute(): Construct an empty attribute.

TiXmlAttribute(const std::string & _name, const std::string & _value): std::string constructor.

TiXmlAttribute(const char * _name, const char * _value): Construct an attribute with a name and value.

const char * Name(): Return the name of this attribute.

const char * Value(): Return the value of this attribute.

const std::string & ValueStr(): Return the value of this attribute.

int IntValue(): Return the value of this attribute, converted to an integer.

double DoubleValue(): Return the value of this attribute, converted to a double.

const TIXML_STRING & NameTStr()

int QueryIntValue(int * _value)

QueryIntValue examines the value string.

It is an alternative to the IntValue() method with richer error checking. If the value is an integer, it is stored in ‘value’ and the call returns TIXML_SUCCESS. If it is not an integer, it returns TIXML_WRONG_TYPE.

A specialized but useful call. Note that for success it returns 0, which is the opposite of almost all other TinyXml calls.

int QueryDoubleValue(double * _value): QueryDoubleValue examines the value string. See QueryIntValue().

void SetName(const char * _name): Set the name of this attribute.

void SetValue(const char * _value): Set the value.

void SetIntValue(int _value): Set the value from an integer.

void SetDoubleValue(double _value): Set the value from a double.

void SetName(const std::string & _name): STL std::string form.

void SetValue(const std::string & _value): STL std::string form.

const TiXmlAttribute * Next(): Get the next sibling attribute in the DOM. Returns null at end.

TiXmlAttribute * Next()

const TiXmlAttribute * Previous(): Get the previous sibling attribute in the DOM. Returns null at beginning.

TiXmlAttribute * Previous()

bool operator==(const TiXmlAttribute & rhs)

bool operator<(const TiXmlAttribute & rhs)

bool operator>(const TiXmlAttribute & rhs)

const char * Parse(const char * p, TiXmlParsingData * data, TiXmlEncoding encoding)

void Print(FILE * cfile, int depth)

All TinyXml classes can print themselves to a file stream or the string class (TiXmlString in non-STL mode, std::string in STL mode.) Either or both cfile and str can be null.

This is a formatted print, and will insert tabs and newlines.

(For an unformatted stream, use the << operator.)

void Print(FILE * cfile, int depth, TIXML_STRING * str)

void SetDocument(TiXmlDocument * doc)

Private Functions

TiXmlAttribute(const TiXmlAttribute &)

void operator=(const TiXmlAttribute & base)

Private Members

TiXmlDocument * document

TIXML_STRING name

TIXML_STRING value

TiXmlAttribute * prev

TiXmlAttribute * next

Friends

friend class TiXmlAttributeSet

class TiXmlAttributeSet

Public Functions

TiXmlAttributeSet()

~TiXmlAttributeSet()

void Add(TiXmlAttribute * attribute)

void Remove(TiXmlAttribute * attribute)

const TiXmlAttribute * First()

TiXmlAttribute * First()

const TiXmlAttribute * Last()

TiXmlAttribute * Last()

const TiXmlAttribute * Find(const char * _name)

TiXmlAttribute * Find(const char * _name)

const TiXmlAttribute * Find(const std::string & _name)

TiXmlAttribute * Find(const std::string & _name)

Private Functions

TiXmlAttributeSet(const TiXmlAttributeSet &)

void operator=(const TiXmlAttributeSet &)

Private Members

TiXmlAttribute sentinel

class TiXmlBase

#include <tinyxml.h>

TiXmlBase is a base class for every class in TinyXml.

It does little except to establish that TinyXml classes can be printed and provide some utility functions.

In XML, the document and elements can contain other elements and other types of nodes.

A Document can contain: Element (container or leaf)
                        Comment (leaf)
                        Unknown (leaf)
                        Declaration( leaf )

An Element can contain: Element (container or leaf)
                        Text    (leaf)
                        Attributes (not on tree)
                        Comment (leaf)
                        Unknown (leaf)

A Decleration contains: Attributes (not on tree)

Public Type

Anonymous enum

Values:

TIXML_NO_ERROR = = 0 -
TIXML_ERROR -
TIXML_ERROR_OPENING_FILE -
TIXML_ERROR_OUT_OF_MEMORY -
TIXML_ERROR_PARSING_ELEMENT -
TIXML_ERROR_FAILED_TO_READ_ELEMENT_NAME -
TIXML_ERROR_READING_ELEMENT_VALUE -
TIXML_ERROR_READING_ATTRIBUTES -
TIXML_ERROR_PARSING_EMPTY -
TIXML_ERROR_READING_END_TAG -
TIXML_ERROR_PARSING_UNKNOWN -
TIXML_ERROR_PARSING_COMMENT -
TIXML_ERROR_PARSING_DECLARATION -
TIXML_ERROR_DOCUMENT_EMPTY -
TIXML_ERROR_EMBEDDED_NULL -
TIXML_ERROR_PARSING_CDATA -
TIXML_ERROR_DOCUMENT_TOP_ONLY -
TIXML_ERROR_STRING_COUNT -

Public Functions

TiXmlBase()

~TiXmlBase()

void Print(FILE * cfile, int depth)

All TinyXml classes can print themselves to a file stream or the string class (TiXmlString in non-STL mode, std::string in STL mode.) Either or both cfile and str can be null.

This is a formatted print, and will insert tabs and newlines.

(For an unformatted stream, use the << operator.)

int Row()

Return the position, in the original source file, of this node or attribute.

The row and column are 1-based. (That is the first row and first column is 1,1). If the returns values are 0 or less, then the parser does not have a row and column value.

Generally, the row and column value will be set when the TiXmlDocument::Load(), TiXmlDocument::LoadFile(), or any TiXmlNode::Parse() is called. It will NOT be set when the DOM was created from operator>>.

The values reflect the initial load. Once the DOM is modified programmatically (by adding or changing nodes and attributes) the new values will NOT update to reflect changes in the document.

There is a minor performance cost to computing the row and column. Computation can be disabled if TiXmlDocument::SetTabSize() is called with 0 as the value.

See: TiXmlDocument::SetTabSize()

int Column(): See Row()

void SetUserData(void * user): Set a pointer to arbitrary user data.

void * GetUserData(): Get a pointer to arbitrary user data.

const void * GetUserData(): Get a pointer to arbitrary user data.

const char * Parse(const char * p, TiXmlParsingData * data, TiXmlEncoding encoding)

Public Static Functions

void SetCondenseWhiteSpace(bool condense)

The world does not agree on whether white space should be kept or not.

In order to make everyone happy, these global, static functions are provided to set whether or not TinyXml will condense all white space into a single space or not. The default is to condense. Note changing this value is not thread safe.

bool IsWhiteSpaceCondensed(): Return the current white space setting.

Public Static Attributes

const int utf8ByteTable[256]

Protected Attributes

TiXmlCursor location

void * userData: Field containing a generic user pointer.

Protected Static Functions

const char * SkipWhiteSpace(const char *, TiXmlEncoding encoding)

bool IsWhiteSpace(char c)

bool IsWhiteSpace(int c)

bool StreamWhiteSpace(std::istream * in, TIXML_STRING * tag)

bool StreamTo(std::istream * in, int character, TIXML_STRING * tag)

const char * ReadName(const char * p, TIXML_STRING * name, TiXmlEncoding encoding)

const char * ReadText(const char * in, TIXML_STRING * text, bool ignoreWhiteSpace, const char * endTag, bool ignoreCase, TiXmlEncoding encoding)

const char * GetEntity(const char * in, char * value, int * length, TiXmlEncoding encoding)

const char * GetChar(const char * p, char * _value, int * length, TiXmlEncoding encoding)

void PutString(const TIXML_STRING & str, TIXML_STRING * out)

bool StringEqual(const char * p, const char * endTag, bool ignoreCase, TiXmlEncoding encoding)

int IsAlpha(unsigned char anyByte, TiXmlEncoding encoding)

int IsAlphaNum(unsigned char anyByte, TiXmlEncoding encoding)

int ToLower(int v, TiXmlEncoding encoding)

void ConvertUTF32ToUTF8(unsigned long input, char * output, int * length)

Protected Static Attributes

const char * errorString[TIXML_ERROR_STRING_COUNT]

Private Types

Anonymous enum

Values:

NUM_ENTITY = = 5 -
MAX_ENTITY_LENGTH = = 6 -

Private Functions

TiXmlBase(const TiXmlBase &)

void operator=(const TiXmlBase & base)

Private Static Attributes

Entity entity[NUM_ENTITY]

bool condenseWhiteSpace

Friends

friend class TiXmlNode

friend class TiXmlElement

friend class TiXmlDocument

class TiXmlComment

#include <tinyxml.h>

An XML comment.

Public Functions

TiXmlComment(): Constructs an empty comment.

TiXmlComment(const char * _value): Construct a comment from text.

TiXmlComment(const TiXmlComment &)

void operator=(const TiXmlComment & base)

~TiXmlComment()

TiXmlNode * Clone(): Returns a copy of this Comment.

void Print(FILE * cfile, int depth)

All TinyXml classes can print themselves to a file stream or the string class (TiXmlString in non-STL mode, std::string in STL mode.) Either or both cfile and str can be null.

This is a formatted print, and will insert tabs and newlines.

(For an unformatted stream, use the << operator.)

const char * Parse(const char * p, TiXmlParsingData * data, TiXmlEncoding encoding)

const TiXmlComment * ToComment(): Cast to a more defined type. Will return null not of the requested type.

TiXmlComment * ToComment(): Cast to a more defined type. Will return null not of the requested type.

bool Accept(TiXmlVisitor * visitor): Walk the XML tree visiting this node and all of its children.

Protected Functions

void CopyTo(TiXmlComment * target)

void StreamIn(std::istream * in, TIXML_STRING * tag)

struct TiXmlCursor

Public Functions

TiXmlCursor()

void Clear()

Public Members

int row

int col

class TiXmlDeclaration

#include <tinyxml.h>

In correct XML the declaration is the first entry in the file.

    <?xml version="1.0" standalone="yes"?>

TinyXml will happily read or write files without a declaration, however. There are 3 possible attributes to the declaration: version, encoding, and standalone.

Note: In this version of the code, the attributes are handled as special cases, not generic attributes, simply because there can only be at most 3 and they are always the same.

Public Functions

TiXmlDeclaration(): Construct an empty declaration.

TiXmlDeclaration(const std::string & _version, const std::string & _encoding, const std::string & _standalone): Constructor.

TiXmlDeclaration(const char * _version, const char * _encoding, const char * _standalone): Construct.

TiXmlDeclaration(const TiXmlDeclaration & copy)

void operator=(const TiXmlDeclaration & copy)

~TiXmlDeclaration()

const char * Version(): Version. Will return an empty string if none was found.

const char * Encoding(): Encoding. Will return an empty string if none was found.

const char * Standalone(): Is this a standalone document?

TiXmlNode * Clone(): Creates a copy of this Declaration and returns it.

void Print(FILE * cfile, int depth, TIXML_STRING * str)

void Print(FILE * cfile, int depth)

All TinyXml classes can print themselves to a file stream or the string class (TiXmlString in non-STL mode, std::string in STL mode.) Either or both cfile and str can be null.

This is a formatted print, and will insert tabs and newlines.

(For an unformatted stream, use the << operator.)

const char * Parse(const char * p, TiXmlParsingData * data, TiXmlEncoding encoding)

const TiXmlDeclaration * ToDeclaration(): Cast to a more defined type. Will return null not of the requested type.

TiXmlDeclaration * ToDeclaration(): Cast to a more defined type. Will return null not of the requested type.

bool Accept(TiXmlVisitor * visitor): Walk the XML tree visiting this node and all of its children.

Protected Functions

void CopyTo(TiXmlDeclaration * target)

void StreamIn(std::istream * in, TIXML_STRING * tag)

Private Members

TIXML_STRING version

TIXML_STRING encoding

TIXML_STRING standalone

class TiXmlDocument

#include <tinyxml.h>

Always the top level node.

A document binds together all the XML pieces. It can be saved, loaded, and printed to the screen. The ‘value’ of a document node is the xml file name.

Public Functions

TiXmlDocument(): Create an empty document, that has no name.

TiXmlDocument(const char * documentName): Create a document with a name. The name of the document is also the filename of the xml.

TiXmlDocument(const std::string & documentName): Constructor.

TiXmlDocument(const TiXmlDocument & copy)

void operator=(const TiXmlDocument & copy)

~TiXmlDocument()

bool LoadFile(TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING)

Load a file using the current document value.

Returns true if successful. Will delete any existing document data before loading.

bool SaveFile(): Save a file using the current document value. Returns true if successful.

bool LoadFile(const char * filename, TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING): Load a file using the given filename. Returns true if successful.

bool SaveFile(const char * filename): Save a file using the given filename. Returns true if successful.

bool LoadFile(FILE *, TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING)

Load a file using the given FILE*.

Returns true if successful. Note that this method doesn’t stream - the entire object pointed at by the FILE* will be interpreted as an XML file. TinyXML doesn’t stream in XML from the current file location. Streaming may be added in the future.

bool SaveFile(FILE *): Save a file using the given FILE*. Returns true if successful.

bool LoadFile(const std::string & filename, TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING)

Parameters

encoding -
STL std::string version.

bool SaveFile(const std::string & filename): < STL std::string version.

const char * Parse(const char * p, TiXmlParsingData * data = 0, TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING)

Parse the given null terminated block of xml data.

Passing in an encoding to this method (either TIXML_ENCODING_LEGACY or TIXML_ENCODING_UTF8 will force TinyXml to use that encoding, regardless of what TinyXml might otherwise try to detect.

const TiXmlElement * RootElement()

Get the root element the only top level element of the document.

In well formed XML, there should only be one. TinyXml is tolerant of multiple elements at the document level.

TiXmlElement * RootElement()

bool Error()

If an error occurs, Error will be set to true.

Also,

The ErrorId() will contain the integer identifier of the error (not generally useful)
The ErrorDesc() method will return the name of the error. (very useful)
The ErrorRow() and ErrorCol() will return the location of the error (if known)

const char * ErrorDesc(): Contains a textual (English) description of the error if one occurs.

int ErrorId()

Generally, you probably want the error string ( ErrorDesc() ).

But if you prefer the ErrorId, this function will fetch it.

int ErrorRow()

Returns the location (if known) of the error.

The first column is column 1, and the first row is row 1. A value of 0 means the row and column wasn’t applicable (memory errors, for example, have no row/column) or the parser lost the error. (An error in the error reporting, in that case.)

See: SetTabSize, Row, Column

int ErrorCol(): The column where the error occurred. See ErrorRow()

void SetTabSize(int _tabsize)

SetTabSize() allows the error reporting functions (ErrorRow() and ErrorCol()) to report the correct values for row and column.

It does not change the output or input in any way.

By calling this method, with a tab size greater than 0, the row and column of each node and attribute is stored when the file is loaded. Very useful for tracking the DOM back in to the source file.

The tab size is required for calculating the location of nodes. If not set, the default of 4 is used. The tabsize is set per document. Setting the tabsize to 0 disables row/column tracking.

Note that row and column tracking is not supported when using operator>>.

The tab size needs to be enabled before the parse or load. Correct usage:

TiXmlDocument doc;
doc.SetTabSize( 8 );
doc.Load( "myfile.xml" );

See: Row, Column

int TabSize()

void ClearError()

If you have handled the error, it can be reset with this call.

The error state is automatically cleared if you Parse a new XML block.

void Print(): Write the document to standard out using formatted printing (“pretty print”).

void Print(FILE * cfile, int depth = 0): Print this Document to a FILE stream.

void SetError(int err, const char * errorLocation, TiXmlParsingData * prevData, TiXmlEncoding encoding)

const TiXmlDocument * ToDocument(): Cast to a more defined type. Will return null not of the requested type.

TiXmlDocument * ToDocument(): Cast to a more defined type. Will return null not of the requested type.

bool Accept(TiXmlVisitor * content): Walk the XML tree visiting this node and all of its children.

Protected Functions

TiXmlNode * Clone()

Create an exact duplicate of this node and return it.

The memory must be deleted by the caller.

void StreamIn(std::istream * in, TIXML_STRING * tag)

Private Functions

void CopyTo(TiXmlDocument * target)

Private Members

bool error

int errorId

TIXML_STRING errorDesc

int tabsize

TiXmlCursor errorLocation

bool useMicrosoftBOM

class TiXmlElement

#include <tinyxml.h>

The element is a container class.

It has a value, the element name, and can contain other elements, text, comments, and unknowns. Elements also contain an arbitrary number of attributes.

Public Functions

TiXmlElement(const char * in_value): Construct an element.

TiXmlElement(const std::string & _value): std::string constructor.

TiXmlElement(const TiXmlElement &)

void operator=(const TiXmlElement & base)

~TiXmlElement()

const char * Attribute(const char * name): Given an attribute name, Attribute() returns the value for the attribute of that name, or null if none exists.

const char * Attribute(const char * name, int * i)

Given an attribute name, Attribute() returns the value for the attribute of that name, or null if none exists.

If the attribute exists and can be converted to an integer, the integer value will be put in the return ‘i’, if ‘i’ is non-null.

const char * Attribute(const char * name, double * d)

Given an attribute name, Attribute() returns the value for the attribute of that name, or null if none exists.

If the attribute exists and can be converted to an double, the double value will be put in the return ‘d’, if ‘d’ is non-null.

int QueryIntAttribute(const char * name, int * _value)

QueryIntAttribute examines the attribute - it is an alternative to the Attribute() method with richer error checking.

If the attribute is an integer, it is stored in ‘value’ and the call returns TIXML_SUCCESS. If it is not an integer, it returns TIXML_WRONG_TYPE. If the attribute does not exist, then TIXML_NO_ATTRIBUTE is returned.

int QueryDoubleAttribute(const char * name, double * _value): QueryDoubleAttribute examines the attribute - see QueryIntAttribute().

int QueryFloatAttribute(const char * name, float * _value): QueryFloatAttribute examines the attribute - see QueryIntAttribute().

template <typename T> int QueryValueAttribute(const std::string & name, T * outValue)

Template form of the attribute query which will try to read the attribute into the specified type.

Very easy, very powerful, but be careful to make sure to call this with the correct type.

Return: TIXML_SUCCESS, TIXML_WRONG_TYPE, or TIXML_NO_ATTRIBUTE

void SetAttribute(const char * name, const char * _value)

Sets an attribute of name to a given value.

The attribute will be created if it does not exist, or changed if it does.

const std::string * Attribute(const std::string & name)

const std::string * Attribute(const std::string & name, int * i)

const std::string * Attribute(const std::string & name, double * d)

int QueryIntAttribute(const std::string & name, int * _value)

int QueryDoubleAttribute(const std::string & name, double * _value)

void SetAttribute(const std::string & name, const std::string & _value)

STL std::string form.

void SetAttribute(const std::string & name, int _value)

void SetAttribute(const char * name, int value)

Sets an attribute of name to a given value.

The attribute will be created if it does not exist, or changed if it does.

void SetDoubleAttribute(const char * name, double value)

Sets an attribute of name to a given value.

The attribute will be created if it does not exist, or changed if it does.

void RemoveAttribute(const char * name): Deletes an attribute with the given name.

void RemoveAttribute(const std::string & name): STL std::string form.

const TiXmlAttribute * FirstAttribute(): Access the first attribute in this element.

TiXmlAttribute * FirstAttribute()

const TiXmlAttribute * LastAttribute(): Access the last attribute in this element.

TiXmlAttribute * LastAttribute()

const char * GetText()

Convenience function for easy access to the text inside an element.

Although easy and concise, GetText() is limited compared to getting the TiXmlText child and accessing it directly.

If the first child of ‘this’ is a TiXmlText, the GetText() returns the character string of the Text node, else null is returned.

This is a convenient method for getting the text of simple contained text:

<foo>This is text</foo>
const char* str = fooElement->GetText();

‘str’ will be a pointer to “This is text”.

Note that this function can be misleading. If the element foo was created from this XML:

<foo><b>This is text</b></foo>

then the value of str would be null. The first child node isn’t a text node, it is another element. From this XML:

<foo>This is <b>text</b></foo>

GetText() will return “This is ”.

WARNING: GetText() accesses a child node - don’t become confused with the similarly named TiXmlHandle::Text() and TiXmlNode::ToText() which are safe type casts on the referenced node.

TiXmlNode * Clone(): Creates a new Element and returns it - the returned element is a copy.

void Print(FILE * cfile, int depth)

All TinyXml classes can print themselves to a file stream or the string class (TiXmlString in non-STL mode, std::string in STL mode.) Either or both cfile and str can be null.

This is a formatted print, and will insert tabs and newlines.

(For an unformatted stream, use the << operator.)

const char * Parse(const char * p, TiXmlParsingData * data, TiXmlEncoding encoding)

const TiXmlElement * ToElement(): Cast to a more defined type. Will return null not of the requested type.

TiXmlElement * ToElement(): Cast to a more defined type. Will return null not of the requested type.

bool Accept(TiXmlVisitor * visitor): Walk the XML tree visiting this node and all of its children.

Protected Functions

void CopyTo(TiXmlElement * target)

void ClearThis()

void StreamIn(std::istream * in, TIXML_STRING * tag)

const char * ReadValue(const char * in, TiXmlParsingData * prevData, TiXmlEncoding encoding)

Private Members

TiXmlAttributeSet attributeSet

class TiXmlHandle

#include <tinyxml.h>

A TiXmlHandle is a class that wraps a node pointer with null checks; this is an incredibly useful thing.

Note that TiXmlHandle is not part of the TinyXml DOM structure. It is a separate utility class.

Take an example:

<Document>
    <Element attributeA = "valueA">
        <Child attributeB = "value1" />
        <Child attributeB = "value2" />
    </Element>
<Document>

Assuming you want the value of “attributeB” in the second “Child” element, it’s very easy to write a lot of code that looks like:

TiXmlElement* root = document.FirstChildElement( "Document" );
if ( root )
{
    TiXmlElement* element = root->FirstChildElement( "Element" );
    if ( element )
    {
        TiXmlElement* child = element->FirstChildElement( "Child" );
        if ( child )
        {
            TiXmlElement* child2 = child->NextSiblingElement( "Child" );
            if ( child2 )
            {
                // Finally do something useful.

And that doesn’t even cover “else” cases. TiXmlHandle addresses the verbosity of such code. A TiXmlHandle checks for null pointers so it is perfectly safe and correct to use:

TiXmlHandle docHandle( &document );
TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).ToElement();
if ( child2 )
{
    // do something useful

Which is MUCH more concise and useful.

It is also safe to copy handles - internally they are nothing more than node pointers.

TiXmlHandle handleCopy = handle;

What they should not be used for is iteration:

int i=0; 
while ( true )
{
    TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", i ).ToElement();
    if ( !child )
        break;
    // do something
    ++i;
}

It seems reasonable, but it is in fact two embedded while loops. The Child method is a linear walk to find the element, so this code would iterate much more than it needs to. Instead, prefer:

TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).FirstChild( "Child" ).ToElement();

for( child; child; child=child->NextSiblingElement() )
{
    // do something
}

Public Functions

TiXmlHandle(TiXmlNode * _node): Create a handle from any node (at any depth of the tree.) This can be a null pointer.

TiXmlHandle(const TiXmlHandle & ref): Copy constructor.

TiXmlHandle operator=(const TiXmlHandle & ref)

TiXmlHandle FirstChild(): Return a handle to the first child node.

TiXmlHandle FirstChild(const char * value): Return a handle to the first child node with the given name.

TiXmlHandle FirstChildElement(): Return a handle to the first child element.

TiXmlHandle FirstChildElement(const char * value): Return a handle to the first child element with the given name.

TiXmlHandle Child(const char * value, int index)

Return a handle to the “index” child with the given name.

The first child is 0, the second 1, etc.

TiXmlHandle Child(int index)

Return a handle to the “index” child.

The first child is 0, the second 1, etc.

TiXmlHandle ChildElement(const char * value, int index)

Return a handle to the “index” child element with the given name.

The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted.

TiXmlHandle ChildElement(int index)

Return a handle to the “index” child element.

The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted.

TiXmlHandle FirstChild(const std::string & _value)

TiXmlHandle FirstChildElement(const std::string & _value)

TiXmlHandle Child(const std::string & _value, int index)

TiXmlHandle ChildElement(const std::string & _value, int index)

TiXmlNode * ToNode()

Return the handle as a TiXmlNode.

This may return null.

TiXmlElement * ToElement()

Return the handle as a TiXmlElement.

This may return null.

TiXmlText * ToText()

Return the handle as a TiXmlText.

This may return null.

TiXmlUnknown * ToUnknown()

Return the handle as a TiXmlUnknown.

This may return null.

TiXmlNode * Node()

TiXmlElement * Element()

TiXmlText * Text()

TiXmlUnknown * Unknown()

Private Members

TiXmlNode * node

class TiXmlNode

#include <tinyxml.h>

The parent class for everything in the Document Object Model.

(Except for attributes). Nodes have siblings, a parent, and children. A node can be in a document, or stand on its own. The type of a TiXmlNode can be queried, and it can be cast to its more defined type.

Public Type

NodeType enum

The types of XML nodes supported by TinyXml.

(All the unsupported types are picked up by UNKNOWN.)

Values:

DOCUMENT -
ELEMENT -
COMMENT -
UNKNOWN -
TEXT -
DECLARATION -
TYPECOUNT -

Public Functions

~TiXmlNode()

const char * Value()

The meaning of ‘value’ changes for the specific type of TiXmlNode.

Document:   filename of the xml file
Element:    name of the element
Comment:    the comment text
Unknown:    the tag contents
Text:       the text string

The subclasses will wrap this function.

const std::string & ValueStr()

Return Value() as a std::string.

If you only use STL, this is more efficient than calling Value(). Only available in STL mode.

void SetValue(const char * _value)

Changes the value of the node.

Defined as:

Document:   filename of the xml file
Element:    name of the element
Comment:    the comment text
Unknown:    the tag contents
Text:       the text string

void SetValue(const std::string & _value): STL std::string form.

void Clear(): Delete all the children of this node. Does not affect ‘this’.

TiXmlNode * Parent(): One step up the DOM.

const TiXmlNode * Parent()

const TiXmlNode * FirstChild(): The first child of this node. Will be null if there are no children.

TiXmlNode * FirstChild()

const TiXmlNode * FirstChild(const char * value)

The first child of this node with the matching ‘value’.

Will be null if none found.

TiXmlNode * FirstChild(const char * _value): The first child of this node with the matching ‘value’. Will be null if none found.

const TiXmlNode * LastChild()

TiXmlNode * LastChild(): The last child of this node. Will be null if there are no children.

const TiXmlNode * LastChild(const char * value)

TiXmlNode * LastChild(const char * _value): The last child of this node matching ‘value’. Will be null if there are no children.

const TiXmlNode * FirstChild(const std::string & _value): STL std::string form.

TiXmlNode * FirstChild(const std::string & _value): STL std::string form.

const TiXmlNode * LastChild(const std::string & _value): STL std::string form.

TiXmlNode * LastChild(const std::string & _value): STL std::string form.

const TiXmlNode * IterateChildren(const TiXmlNode * previous)

An alternate way to walk the children of a node.

One way to iterate over nodes is:

    for( child = parent->FirstChild(); child; child = child->NextSibling() )

IterateChildren does the same thing with the syntax:

    child = 0;
    while( child = parent->IterateChildren( child ) )

IterateChildren takes the previous child as input and finds the next one. If the previous child is null, it returns the first. IterateChildren will return null when done.

TiXmlNode * IterateChildren(const TiXmlNode * previous)

const TiXmlNode * IterateChildren(const char * value, const TiXmlNode * previous): This flavor of IterateChildren searches for children with a particular ‘value’.

TiXmlNode * IterateChildren(const char * _value, const TiXmlNode * previous)

const TiXmlNode * IterateChildren(const std::string & _value, const TiXmlNode * previous): STL std::string form.

TiXmlNode * IterateChildren(const std::string & _value, const TiXmlNode * previous): STL std::string form.

TiXmlNode * InsertEndChild(const TiXmlNode & addThis)

Add a new node related to this.

Adds a child past the LastChild. Returns a pointer to the new object or NULL if an error occurred.

TiXmlNode * LinkEndChild(TiXmlNode * addThis)

Add a new node related to this.

Adds a child past the LastChild.

NOTE: the node to be added is passed by pointer, and will be henceforth owned (and deleted) by tinyXml. This method is efficient and avoids an extra copy, but should be used with care as it uses a different memory model than the other insert functions.

See: InsertEndChild

TiXmlNode * InsertBeforeChild(TiXmlNode * beforeThis, const TiXmlNode & addThis)

Add a new node related to this.

Adds a child before the specified child. Returns a pointer to the new object or NULL if an error occurred.

TiXmlNode * InsertAfterChild(TiXmlNode * afterThis, const TiXmlNode & addThis)

Add a new node related to this.

Adds a child after the specified child. Returns a pointer to the new object or NULL if an error occurred.

TiXmlNode * ReplaceChild(TiXmlNode * replaceThis, const TiXmlNode & withThis)

Replace a child of this node.

Returns a pointer to the new object or NULL if an error occurred.

bool RemoveChild(TiXmlNode * removeThis): Delete a child of this node.

const TiXmlNode * PreviousSibling(): Navigate to a sibling node.

TiXmlNode * PreviousSibling()

const TiXmlNode * PreviousSibling(const char *): Navigate to a sibling node.

TiXmlNode * PreviousSibling(const char * _prev)

const TiXmlNode * PreviousSibling(const std::string & _value): STL std::string form.

TiXmlNode * PreviousSibling(const std::string & _value): STL std::string form.

const TiXmlNode * NextSibling(const std::string & _value): STL std::string form.

TiXmlNode * NextSibling(const std::string & _value): STL std::string form.

const TiXmlNode * NextSibling(): Navigate to a sibling node.

TiXmlNode * NextSibling()

const TiXmlNode * NextSibling(const char *): Navigate to a sibling node with the given ‘value’.

TiXmlNode * NextSibling(const char * _next)

const TiXmlElement * NextSiblingElement()

Convenience function to get through elements.

Calls NextSibling and ToElement. Will skip all non-Element nodes. Returns 0 if there is not another element.

TiXmlElement * NextSiblingElement()

const TiXmlElement * NextSiblingElement(const char *)

Convenience function to get through elements.

Calls NextSibling and ToElement. Will skip all non-Element nodes. Returns 0 if there is not another element.

TiXmlElement * NextSiblingElement(const char * _next)

const TiXmlElement * NextSiblingElement(const std::string & _value): STL std::string form.

TiXmlElement * NextSiblingElement(const std::string & _value): STL std::string form.

const TiXmlElement * FirstChildElement(): Convenience function to get through elements.

TiXmlElement * FirstChildElement()

const TiXmlElement * FirstChildElement(const char * _value): Convenience function to get through elements.

TiXmlElement * FirstChildElement(const char * _value)

const TiXmlElement * FirstChildElement(const std::string & _value): STL std::string form.

TiXmlElement * FirstChildElement(const std::string & _value): STL std::string form.

int Type()

Query the type (as an enumerated value, above) of this node.

The possible types are: DOCUMENT, ELEMENT, COMMENT, UNKNOWN, TEXT, and DECLARATION.

const TiXmlDocument * GetDocument()

Return a pointer to the Document this node lives in.

Returns null if not in a document.

TiXmlDocument * GetDocument()

bool NoChildren(): Returns true if this node has no children.

const TiXmlDocument * ToDocument(): Cast to a more defined type. Will return null if not of the requested type.

const TiXmlElement * ToElement(): Cast to a more defined type. Will return null if not of the requested type.

const TiXmlComment * ToComment(): Cast to a more defined type. Will return null if not of the requested type.

const TiXmlUnknown * ToUnknown(): Cast to a more defined type. Will return null if not of the requested type.

const TiXmlText * ToText(): Cast to a more defined type. Will return null if not of the requested type.

const TiXmlDeclaration * ToDeclaration(): Cast to a more defined type. Will return null if not of the requested type.

TiXmlDocument * ToDocument(): Cast to a more defined type. Will return null if not of the requested type.

TiXmlElement * ToElement(): Cast to a more defined type. Will return null if not of the requested type.

TiXmlComment * ToComment(): Cast to a more defined type. Will return null if not of the requested type.

TiXmlUnknown * ToUnknown(): Cast to a more defined type. Will return null if not of the requested type.

TiXmlText * ToText(): Cast to a more defined type. Will return null if not of the requested type.

TiXmlDeclaration * ToDeclaration(): Cast to a more defined type. Will return null if not of the requested type.

TiXmlNode * Clone()

Create an exact duplicate of this node and return it.

The memory must be deleted by the caller.

bool Accept(TiXmlVisitor * visitor)

Accept a hierarchical visit the nodes in the TinyXML DOM.

Every node in the XML tree will be conditionally visited and the host will be called back via the TiXmlVisitor interface.

This is essentially a SAX interface for TinyXML. (Note however it doesn’t re-parse the XML for the callbacks, so the performance of TinyXML is unchanged by using this interface versus any other.)

The interface has been based on ideas from:

Which are both good references for “visiting”.

An example of using Accept():

TiXmlPrinter printer;
tinyxmlDoc.Accept( &printer );
const char* xmlcstr = printer.CStr();

Protected Functions

TiXmlNode(NodeType _type)

void CopyTo(TiXmlNode * target)

void StreamIn(std::istream * in, TIXML_STRING * tag)

TiXmlNode * Identify(const char * start, TiXmlEncoding encoding)

Protected Attributes

TiXmlNode * parent

NodeType type

TiXmlNode * firstChild

TiXmlNode * lastChild

TIXML_STRING value

TiXmlNode * prev

TiXmlNode * next

Private Functions

TiXmlNode(const TiXmlNode &)

void operator=(const TiXmlNode & base)

Friends

friend class TiXmlDocument

friend class TiXmlElement

friend std::istream & operator>>

An input stream operator, for every class.

Tolerant of newlines and formatting, but doesn’t expect them.

friend std::ostream & operator<<

An output stream operator, for every class.

Note that this outputs without any newlines or formatting, as opposed to Print(), which includes tabs and new lines.

The operator<< and operator>> are not completely symmetric. Writing a node to a stream is very well defined. You’ll get a nice stream of output, without any extra whitespace or newlines.

But reading is not as well defined. (As it always is.) If you create a TiXmlElement (for example) and read that from an input stream, the text needs to define an element or junk will result. This is true of all input streams, but it’s worth keeping in mind.

A TiXmlDocument will read nodes until it reads a root element, and all the children of that root element.

friend std::string & operator<<: Appends the XML node or attribute to a std::string.

class TiXmlPrinter

#include <tinyxml.h>

Print to memory functionality.

The TiXmlPrinter is useful when you need to:

Print to memory (especially in non-STL mode)
Control formatting (line endings, etc.)

When constructed, the TiXmlPrinter is in its default “pretty printing” mode. Before calling Accept() you can call methods to control the printing of the XML document. After TiXmlNode::Accept() is called, the printed document can be accessed via the CStr(), Str(), and Size() methods.

TiXmlPrinter uses the Visitor API.

TiXmlPrinter printer;
printer.SetIndent( "\t" );

doc.Accept( &printer );
fprintf( stdout, "%s", printer.CStr() );

Public Functions

TiXmlPrinter()

bool VisitEnter(const TiXmlDocument &): Visit a document.

bool VisitExit(const TiXmlDocument &): Visit a document.

bool VisitEnter(const TiXmlElement &, const TiXmlAttribute *): Visit an element.

bool VisitExit(const TiXmlElement &): Visit an element.

bool Visit(const TiXmlDeclaration &): Visit a declaration.

bool Visit(const TiXmlText &): Visit a text node.

bool Visit(const TiXmlComment &): Visit a comment node.

bool Visit(const TiXmlUnknown &): Visit an unknown node.

void SetIndent(const char * _indent)

Set the indent characters for printing.

By default 4 spaces but tab () is also useful, or null/empty string for no indentation.

const char * Indent(): Query the indention string.

void SetLineBreak(const char * _lineBreak)

Set the line breaking string.

By default set to newline ( ). Some operating systems prefer other characters, or can be set to the null/empty string for no indentation.

const char * LineBreak(): Query the current line breaking string.

void SetStreamPrinting()

Switch over to “stream printing” which is the most dense formatting without line breaks.

Common when the XML is needed for network transmission.

const char * CStr(): Return the result.

size_t Size(): Return the length of the result string.

const std::string & Str(): Return the result.

Private Functions

void DoIndent()

void DoLineBreak()

Private Members

int depth

bool simpleTextPrint

TIXML_STRING buffer

TIXML_STRING indent

TIXML_STRING lineBreak

class TiXmlText

#include <tinyxml.h>

XML text.

A text node can have 2 ways to output the next. “normal” output and CDATA. It will default to the mode it was parsed from the XML file and you generally want to leave it alone, but you can change the output mode with SetCDATA() and query it with CDATA().

Public Functions

TiXmlText(const char * initValue)

Constructor for text element.

By default, it is treated as normal, encoded text. If you want it be output as a CDATA text element, set the parameter _cdata to ‘true’

~TiXmlText()

TiXmlText(const std::string & initValue): Constructor.

TiXmlText(const TiXmlText & copy)

void operator=(const TiXmlText & base)

void Print(FILE * cfile, int depth)

All TinyXml classes can print themselves to a file stream or the string class (TiXmlString in non-STL mode, std::string in STL mode.) Either or both cfile and str can be null.

This is a formatted print, and will insert tabs and newlines.

(For an unformatted stream, use the << operator.)

bool CDATA(): Queries whether this represents text using a CDATA section.

void SetCDATA(bool _cdata): Turns on or off a CDATA representation of text.

const char * Parse(const char * p, TiXmlParsingData * data, TiXmlEncoding encoding)

const TiXmlText * ToText(): Cast to a more defined type. Will return null not of the requested type.

TiXmlText * ToText(): Cast to a more defined type. Will return null not of the requested type.

bool Accept(TiXmlVisitor * content): Walk the XML tree visiting this node and all of its children.

Protected Functions

TiXmlNode * Clone(): [internal use] Creates a new Element and returns it.

void CopyTo(TiXmlText * target)

bool Blank()

void StreamIn(std::istream * in, TIXML_STRING * tag)

Private Members

bool cdata

Friends

friend class TiXmlElement

class TiXmlUnknown

#include <tinyxml.h>

Any tag that tinyXml doesn’t recognize is saved as an unknown.

It is a tag of text, but should not be modified. It will be written back to the XML, unchanged, when the file is saved.

DTD tags get thrown into TiXmlUnknowns.

Public Functions

TiXmlUnknown()

~TiXmlUnknown()

TiXmlUnknown(const TiXmlUnknown & copy)

void operator=(const TiXmlUnknown & copy)

TiXmlNode * Clone(): Creates a copy of this Unknown and returns it.

void Print(FILE * cfile, int depth)

All TinyXml classes can print themselves to a file stream or the string class (TiXmlString in non-STL mode, std::string in STL mode.) Either or both cfile and str can be null.

This is a formatted print, and will insert tabs and newlines.

(For an unformatted stream, use the << operator.)

const char * Parse(const char * p, TiXmlParsingData * data, TiXmlEncoding encoding)

const TiXmlUnknown * ToUnknown(): Cast to a more defined type. Will return null not of the requested type.

TiXmlUnknown * ToUnknown(): Cast to a more defined type. Will return null not of the requested type.

bool Accept(TiXmlVisitor * content): Walk the XML tree visiting this node and all of its children.

Protected Functions

void CopyTo(TiXmlUnknown * target)

void StreamIn(std::istream * in, TIXML_STRING * tag)

class TiXmlVisitor

#include <tinyxml.h>

If you call the Accept() method, it requires being passed a TiXmlVisitor class to handle callbacks.

For nodes that contain other nodes (Document, Element) you will get called with a VisitEnter/VisitExit pair. Nodes that are always leaves are simple called with Visit().

If you return ‘true’ from a Visit method, recursive parsing will continue. If you return false, no children of this node or its sibilings will be Visited.

All flavors of Visit methods have a default implementation that returns ‘true’ (continue visiting). You need to only override methods that are interesting to you.

Generally Accept() is called on the TiXmlDocument, although all nodes support Visiting.

You should never change the document from a callback.

See: TiXmlNode::Accept()

Public Functions

~TiXmlVisitor()

bool VisitEnter(const TiXmlDocument &): Visit a document.

bool VisitExit(const TiXmlDocument &): Visit a document.

bool VisitEnter(const TiXmlElement &, const TiXmlAttribute *): Visit an element.

bool VisitExit(const TiXmlElement &): Visit an element.

bool Visit(const TiXmlDeclaration &): Visit a declaration.

bool Visit(const TiXmlText &): Visit a text node.

bool Visit(const TiXmlComment &): Visit a comment node.

bool Visit(const TiXmlUnknown &): Visit an unknown node.

file tinyxml.h

#include <ctype.h>#include <stdio.h>#include <stdlib.h>#include <string.h>#include <assert.h>#include <string>#include <iostream>#include <sstream>

Defines

TIXML_USE_STL

TIXML_STRING

TIXML_SAFE

Enums

Anonymous enum

Values:

TIXML_SUCCESS -
TIXML_NO_ATTRIBUTE -
TIXML_WRONG_TYPE -

TiXmlEncoding enum

Values:

TIXML_ENCODING_UNKNOWN -
TIXML_ENCODING_UTF8 -
TIXML_ENCODING_LEGACY -

Variables

const int TIXML_MAJOR_VERSION

const int TIXML_MINOR_VERSION

const int TIXML_PATCH_VERSION

const TiXmlEncoding TIXML_DEFAULT_ENCODING

page deprecated

Specific Examples Test Suite¶

Typedef Examples¶

class TypeDefTest

file typedef.h

Typedefs

typedef TypeDefTest (* TypeDefTestFuncPtr)(void)

typedef void *(* voidFuncPtr)(float, int)

typedef void * voidPointer

typedef float * floatPointer

typedef float floatingPointNumber

Namespaced Function Examples¶

void function(): namespaced class function

void function(): second namespaced class function

void anotherFunction(): second namespaced class other function

void function(): non-namespaced class function

void anotherFunction(): non-namespaced class other function

Alias Example¶

void frob_foos(void * Frobs)

Foo frob routine.

bob this something else

Side Effects

Frobs any foos.

Return

Frobs any foos.

bob this something else

Side Effects

Frobs any foos.

Parameters

Frobs -
any foos.

Fixed Width Font¶

class Out

Public Functions

Out(): Constructor for Out object

~Out(): Destructor for Out object

Function Overloads¶

void f(int, int): Function which takes two int arguments.

void f(double, double): Function which takes two double arguments.

void g(int, int): Another function which takes two int arguments.

void g(double, double): Another function which takes two double arguments.

void h(std::string, MyType): Another function which takes a custom type.

void h(std::string, MyOtherType): Another function which takes another custom type.

void h(std::string, int): Another function which takes a basic type.

Program Listing¶

class Vector: Vector class

Vector center()

The center of the InteractionBox in device coordinates (millimeters). This point is equidistant from all sides of the box.

Vector boxCenter = interactionBox.center();
Vector max = interactionBox.max();
Vector diff = max - boxCenter;

Return: The InteractionBox center in device coordinates.
Since: 1.0

Image¶

class ImageClass

This is a class with an image in the description.

It renders like this:

_images/imageExample.png

Breathe & Sphinx should automatically copy the image from the doxygen output directory into the _images folder of the Sphinx output.

Embedded ReStructuredText¶

class TestClass

#include <rst.h>

first class inside of namespace

Public Functions

void function()

Inserting additional reStructuredText information.

This is some funky non-XML compliant text: <& !><

Note

This reStructuredText has been handled correctly.

This is just a standard verbatim block with code:

    child = 0;
    while( child = parent->IterateChildren( child ) )

void rawVerbatim()

Inserting additional reStructuredText information.

Note

This reStructuredText has been handled correctly.

void rawLeadingAsteriskVerbatim()

Inserting additional reStructuredText information.

Some example code:

int example(int x) {
    return x * 2;
}

void testFunction(): Brief description.

file rst.h

Inline Parameter Documentation¶

This is currently flawed as it doesn’t know where to sensibly put the parameters in the final description.

It currently defaults to the top of the detail description block which means it comes between the brief description text and the detailed description text which is less than ideal, but attempts to programmatically figure out where the detail description text ends have failed. Something for future work.

Example¶

class Test

Public Functions

const char * member(char c, int n)

A member function.

Parameters

c -
c a character.
n -
n an integer.

Details about member function

Return

a character pointer.

Exceptions

std::out_of_range -
parameter is out of range.

file inline.h

Members Tests¶

All Members¶

class testnamespace::NamespacedClassTest

first class inside of namespace

Public Functions

void function(): namespaced class function

NamespacedClassTest()

Specific Members¶

class testnamespace::NamespacedClassTest

first class inside of namespace

Protected Static Functions

void functionS(): Some kind of function.

Private Functions

void anotherFunction(): namespaced class other function

No Members¶

class testnamespace::NamespacedClassTest

first class inside of namespace

Credits¶

Thank you to:

For their contributions; reporting bugs, suggesting features, improving the code and working on the documentation. And thanks to:

Dimitri van Heesch for Doxygen.
Georg Brandl for Sphinx.
David Goodger for Docutils and reStructuredText.

And thank you to whoever made the haiku theme for Sphinx.

Download¶

Breathe is available from:

Licence¶

Breathe is under the BSD licence.

In a Nutshell¶

You write code that looks a little like this:

/**
    \file nutshell.h
    An overly extended example of how to use breathe
*/

/*!
    With a little bit of a elaboration, should you feel it necessary.
*/
class Nutshell
{
public:

    //! Our tool set
    /*! The various tools we can opt to use to crack this particular nut */
    enum Tool
    {
        kHammer = 0,          //!< What? It does the job
        kNutCrackers,         //!< Boring
        kNinjaThrowingStars   //!< Stealthy
    };

    //! Nutshell constructor
    Nutshell();

    //! Nutshell destructor
    ~Nutshell();

    /*! Crack that shell with specified tool

      \param tool - the tool with which to crack the nut
    */
    void crack( Tool tool );

    /*!
      \return Whether or not the nut is cracked
    */
    bool isCracked();

private:

    //! Our cracked state
    bool m_isCracked;

};

Then you run this:

doxygen

With a setting that says this:

GENERATE_XML = YES

Then in your Sphinx documentation, you add something like this:

.. doxygenclass:: Nutshell
   :project: nutshell
   :members:

With a conf.py setting like this:

breathe_projects = {
    "nutshell":"../../examples/specific/nutshell/xml/",
    }

And Breathe registered as an extension in conf.py like this:

extensions = [ "breathe" ]

You get something like this:

class Nutshell

With a little bit of a elaboration, should you feel it necessary.

Public Type

Tool enum

Our tool set.

The various tools we can opt to use to crack this particular nut

Values:

kHammer = = 0 -
What? It does the job.
kNutCrackers -
Boring.
kNinjaThrowingStars -
Stealthy.

Public Functions

Nutshell(): Nutshell constructor.

~Nutshell(): Nutshell destructor.

void crack(Tool tool)

Crack that shell with specified tool

Parameters

tool -
- the tool with which to crack the nut

bool isCracked()

Return: Whether or not the nut is cracked

Sound reasonable? To get started, go checkout the quickstart guide.

Breathe v2.0.0 documentation

Breathe’s documentation¶

Features¶

Contents¶

Quick Start¶

autodoxygenindex Directive Example¶

Working Example¶

doxygenfunction Directive Example¶

Working Example¶

Failing Example¶

doxygenstruct Directive Example¶

Example with Full Description¶

Example with Outline¶

Example with Namespace¶

Failing Example¶

doxygenclass Directive Example¶

Example without Members¶

Example with Members¶

Working Example with Specific Members¶

Example as Outline¶

Failing Example¶

doxygenenum Directive Example¶

Working Example¶

Example with Namespace¶

Failing Example¶

doxygentypedef Directive Example¶

Working Example¶

Example with Namespace¶

Failing Example¶

doxygenunion Directive Example¶

Working Example¶

Example with Namespace¶

Failing Example¶

doxygendefine Directive Example¶

Working Example¶

Failing Example¶

doxygenvariable Directive Example¶

Working Example¶

Failing Example¶

doxygenfile Directive Example¶

Example¶

Example with Nested Namespaces¶

Example for Multiple Files¶

Failing Example¶

doxygengroup Directive Example¶

Example¶

Failing Example¶

autodoxygenfile Directive Example¶

Working Example¶

Supported Markups¶

reStructuredText¶

Handling Leading Asterisks¶

Aliases¶

Domains¶

Class Example¶

Function Examples¶

Custom CSS¶

Groups¶

Lists¶

Template¶

Latex Math¶

Implementation¶

Credits¶

Running on Read the Docs¶

Doxygen Support¶

Generating Doxygen XML Files¶

A More Involved Setup¶

Contributing to Breathe¶

Give It A Go¶

Report Bugs & Suggest Features¶

Improve the Documentation¶

Fork It! And Improve the Code¶

How It Works¶

Parser¶

Doxygen XML Output¶

Doing the Parsing¶

Our Changes¶

Finders¶

More Details, Please¶

Renderers¶