AxioDL
/
tinyxml2
mirror of https://github.com/AxioDL/tinyxml2.git
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #91 from martinsh-shaiters/doxyfix 

Example documentation moved to xmltest.cpp
This commit is contained in:
Lee Thomason 2013-01-15 16:33:10 -08:00
parent dfc494ffc5 c9c8b77d87
commit 980e535aae
3 changed files with 236 additions and 187 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

176
dox
View File

@ -1,4 +1,4 @@
# Doxyfile 1.8.0
# Doxyfile 1.8.3
# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project.
@ -32,7 +32,7 @@ PROJECT_NAME = "TinyXML-2"
# This could be handy for archiving the generated documentation or
# if some version control system is used.
PROJECT_NUMBER = 1.0.9
PROJECT_NUMBER = 1.0.9
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer
@ -126,7 +126,9 @@ FULL_PATH_NAMES = YES
# only done if one of the specified strings matches the left-hand part of
# the path. The tag can be used to show relative paths in the file list.
# If left blank the directory from which doxygen is run is used as the
# path to strip.
# path to strip. Note that you specify absolute paths here, but also
# relative paths, which will be relative from the directory where doxygen is
# started.
STRIP_FROM_PATH =
@ -229,14 +231,15 @@ OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
# Doxygen selects the parser to use depending on the extension of the files it
# parses. With this tag you can assign which parser to use for a given extension.
# Doxygen has a built-in mapping, but you can override or extend it using this
# tag. The format is ext=language, where ext is a file extension, and language
# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C,
# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make
# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C
# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions
# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen.
# parses. With this tag you can assign which parser to use for a given
# extension. Doxygen has a built-in mapping, but you can override or extend it
# using this tag. The format is ext=language, where ext is a file extension,
# and language is one of the parsers supported by doxygen: IDL, Java,
# Javascript, CSharp, C, C++, D, PHP, Objective-C, Python, Fortran, VHDL, C,
# C++. For instance to make doxygen treat .inc files as Fortran files (default
# is PHP), and .f files as C (default is Fortran), use: inc=Fortran f=C. Note
# that for custom extensions you also need to set FILE_PATTERNS otherwise the
# files are not read by doxygen.
EXTENSION_MAPPING =
@ -249,6 +252,13 @@ EXTENSION_MAPPING =
MARKDOWN_SUPPORT = YES
# When enabled doxygen tries to link words that correspond to documented classes,
# or namespaces to their corresponding documentation. Such a link can be
# prevented in individual cases by by putting a % sign in front of the word or
# globally by setting AUTOLINK_SUPPORT to NO.
AUTOLINK_SUPPORT = YES
# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
# to include (a tag file for) the STL sources as input, then you should
# set this tag to YES in order to let doxygen match functions declarations and
@ -269,10 +279,10 @@ CPP_CLI_SUPPORT = NO
SIP_SUPPORT = NO
# For Microsoft's IDL there are propget and propput attributes to indicate getter
# and setter methods for a property. Setting this option to YES (the default)
# will make doxygen replace the get and set methods by a property in the
# documentation. This will only work if the methods are indeed getting or
# For Microsoft's IDL there are propget and propput attributes to indicate
# getter and setter methods for a property. Setting this option to YES (the
# default) will make doxygen replace the get and set methods by a property in
# the documentation. This will only work if the methods are indeed getting or
# setting a simple type. If this is not the case, or you want to show the
# methods anyway, you should set this option to NO.
@ -362,7 +372,8 @@ EXTRACT_ALL = NO
EXTRACT_PRIVATE = NO
# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal scope will be included in the documentation.
# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal
# scope will be included in the documentation.
EXTRACT_PACKAGE = NO
@ -533,7 +544,8 @@ GENERATE_BUGLIST = NO
GENERATE_DEPRECATEDLIST= YES
# The ENABLED_SECTIONS tag can be used to enable conditional
# documentation sections, marked by \if sectionname ... \endif.
# documentation sections, marked by \if section-label ... \endif
# and \cond section-label ... \endcond blocks.
ENABLED_SECTIONS =
@ -553,12 +565,6 @@ MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = YES
# If the sources in your project are distributed over multiple directories
# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy
# in the documentation. The default is NO.
SHOW_DIRECTORIES = NO
# Set the SHOW_FILES tag to NO to disable the generation of the Files page.
# This will remove the Files entry from the Quick Index and from the
# Folder Tree View (if specified). The default is YES.
@ -584,7 +590,7 @@ FILE_VERSION_FILTER =
# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed
# by doxygen. The layout file controls the global structure of the generated
# output files in an output format independent way. The create the layout file
# output files in an output format independent way. To create the layout file
# that represents doxygen's defaults, run doxygen with the -l option.
# You can optionally specify a file name after the option, if omitted
# DoxygenLayout.xml will be used as the name of the layout file.
@ -597,7 +603,8 @@ LAYOUT_FILE =
# requires the bibtex tool to be installed. See also
# http://en.wikipedia.org/wiki/BibTeX for more info. For LaTeX the style
# of the bibliography can be controlled using LATEX_BIB_STYLE. To use this
# feature you need bibtex and perl available in the search path.
# feature you need bibtex and perl available in the search path. Do not use
# file names with spaces, bibtex cannot handle them.
CITE_BIB_FILES =
@ -661,7 +668,9 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
INPUT = tinyxml2.h xmltest.h readme.md
INPUT = tinyxml2.h \
xmltest.cpp \
readme.md
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@ -779,6 +788,13 @@ FILTER_SOURCE_FILES = NO
FILTER_SOURCE_PATTERNS =
# If the USE_MD_FILE_AS_MAINPAGE tag refers to the name of a markdown file that
# is part of the input, its contents will be placed on the main page (index.html).
# This can be useful if you have a project on for instance GitHub and want reuse
# the introduction page also for the doxygen output.
USE_MDFILE_AS_MAINPAGE = readme.md
#---------------------------------------------------------------------------
# configuration options related to source browsing
#---------------------------------------------------------------------------
@ -797,7 +813,7 @@ INLINE_SOURCES = NO
# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
# doxygen to hide any special comment blocks from generated source code
# fragments. Normal C and C++ comments will always remain visible.
# fragments. Normal C, C++ and Fortran comments will always remain visible.
STRIP_CODE_COMMENTS = YES
@ -900,13 +916,23 @@ HTML_FOOTER =
# The HTML_STYLESHEET tag can be used to specify a user-defined cascading
# style sheet that is used by each HTML page. It can be used to
# fine-tune the look of the HTML output. If the tag is left blank doxygen
# will generate a default style sheet. Note that doxygen will try to copy
# the style sheet file to the HTML output directory, so don't put your own
# style sheet in the HTML output directory as well, or it will be erased!
# fine-tune the look of the HTML output. If left blank doxygen will
# generate a default style sheet. Note that it is recommended to use
# HTML_EXTRA_STYLESHEET instead of this one, as it is more robust and this
# tag will in the future become obsolete.
HTML_STYLESHEET =
# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional
# user-defined cascading style sheet that is included after the standard
# style sheets created by doxygen. Using this option one can overrule
# certain style aspects. This is preferred over using HTML_STYLESHEET
# since it does not replace the standard style sheet and is therefor more
# robust against future updates. Doxygen will copy the style sheet file to
# the output directory.
HTML_EXTRA_STYLESHEET =
# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
# other source files which should be copied to the HTML output directory. Note
# that these files will be copied to the base HTML output directory. Use the
@ -947,20 +973,23 @@ HTML_COLORSTYLE_GAMMA = 80
HTML_TIMESTAMP = YES
# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes,
# files or namespaces will be aligned in HTML using tables. If set to
# NO a bullet list will be used.
HTML_ALIGN_MEMBERS = YES
# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML
# documentation will contain sections that can be hidden and shown after the
# page has loaded. For this to work a browser that supports
# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox
# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari).
# page has loaded.
HTML_DYNAMIC_SECTIONS = NO
# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of
# entries shown in the various tree structured indices initially; the user
# can expand and collapse entries dynamically later on. Doxygen will expand
# the tree to such a level that at most the specified number of entries are
# visible (unless a fully collapsed tree already exceeds this amount).
# So setting the number of entries 1 will produce a full collapsed tree by
# default. 0 is a special value representing an infinite number of entries
# and will result in a full expanded tree by default.
HTML_INDEX_NUM_ENTRIES = 100
# If the GENERATE_DOCSET tag is set to YES, additional index files
# will be generated that can be used as input for Apple's Xcode 3
# integrated development environment, introduced with OSX 10.5 (Leopard).
@ -988,9 +1017,9 @@ DOCSET_FEEDNAME = "Doxygen generated docs"
DOCSET_BUNDLE_ID = org.doxygen.Project
# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify
# the documentation publisher. This should be a reverse domain-name style
# string, e.g. com.mycompany.MyDocSet.documentation.
# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely
# identify the documentation publisher. This should be a reverse domain-name
# style string, e.g. com.mycompany.MyDocSet.documentation.
DOCSET_PUBLISHER_ID = org.doxygen.Publisher
@ -1139,11 +1168,6 @@ GENERATE_TREEVIEW = NO
ENUM_VALUES_PER_LINE = 4
# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories,
# and Class Hierarchy pages using a tree view instead of an ordered list.
USE_INLINE_TREES = NO
# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
# used to set the initial width (in pixels) of the frame in which the tree
# is shown.
@ -1180,6 +1204,13 @@ FORMULA_TRANSPARENT = YES
USE_MATHJAX = NO
# When MathJax is enabled you can set the default output format to be used for
# thA MathJax output. Supported types are HTML-CSS, NativeMML (i.e. MathML) and
# SVG. The default value is HTML-CSS, which is slower, but has the best
# compatibility.
MATHJAX_FORMAT = HTML-CSS
# When MathJax is enabled you need to specify the location relative to the
# HTML output directory using the MATHJAX_RELPATH option. The destination
# directory should contain the MathJax.js script. For instance, if the mathjax
@ -1208,15 +1239,50 @@ MATHJAX_EXTENSIONS =
SEARCHENGINE = YES
# When the SERVER_BASED_SEARCH tag is enabled the search engine will be
# implemented using a PHP enabled web server instead of at the web client
# using Javascript. Doxygen will generate the search PHP script and index
# file to put on the web server. The advantage of the server
# based approach is that it scales better to large projects and allows
# full text search. The disadvantages are that it is more difficult to setup
# and does not have live searching capabilities.
# implemented using a web server instead of a web client using Javascript.
# There are two flavours of web server based search depending on the
# EXTERNAL_SEARCH setting. When disabled, doxygen will generate a PHP script for
# searching and an index file used by the script. When EXTERNAL_SEARCH is
# enabled the indexing and searching needs to be provided by external tools.
# See the manual for details.
SERVER_BASED_SEARCH = NO
# When EXTERNAL_SEARCH is enabled doxygen will no longer generate the PHP
# script for searching. Instead the search results are written to an XML file
# which needs to be processed by an external indexer. Doxygen will invoke an
# external search engine pointed to by the SEARCHENGINE_URL option to obtain
# the search results. Doxygen ships with an example indexer (doxyindexer) and
# search engine (doxysearch.cgi) which are based on the open source search engine
# library Xapian. See the manual for configuration details.
EXTERNAL_SEARCH = NO
# The SEARCHENGINE_URL should point to a search engine hosted by a web server
# which will returned the search results when EXTERNAL_SEARCH is enabled.
# Doxygen ships with an example search engine (doxysearch) which is based on
# the open source search engine library Xapian. See the manual for configuration
# details.
SEARCHENGINE_URL =
# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the unindexed
# search data is written to a file for indexing by an external tool. With the
# SEARCHDATA_FILE tag the name of this file can be specified.
SEARCHDATA_FILE = searchdata.xml
# The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through other
# doxygen projects that are not otherwise connected via tags files, but are
# all added to the same search index. Each project needs to have a tag file set
# via GENERATE_TAGFILE. The search mapping then maps the name of the tag file
# to a relative location where the documentation can be found,
# similar to the
# TAGFILES option but without actually processing the tag file.
# The format is: EXTRA_SEARCH_MAPPINGS = tagname1=loc1 tagname2=loc2 ...
EXTRA_SEARCH_MAPPINGS =
#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------
@ -1711,7 +1777,7 @@ CALLER_GRAPH = NO
GRAPHICAL_HIERARCHY = YES
# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES
# If the DIRECTORY_GRAPH and HAVE_DOT tags are set to YES
# then doxygen will show the dependencies a directory has on other directories
# in a graphical way. The dependency relations are determined by the #include
# relations between the files in the directories.

118
xmltest.cpp
View File

@ -79,7 +79,6 @@ void NullLineEndings( char* p )
}
// Comments in the header. (Don't know how to get Doxygen to read comments in this file.)
int example_1()
{
XMLDocument doc;
@ -87,9 +86,17 @@ int example_1()
return doc.ErrorID();
}
/** @page Example-1 Load an XML File
* @dontinclude ./xmltest.cpp
* Basic XML file loading.
* The basic syntax to load an XML file from
* disk and check for an error. (ErrorID()
* will return 0 for no error.)
* @skip example_1()
* @until }
*/
// Comments in the header. (Don't know how to get Doxygen to read comments in this file.)
int example_2()
{
static const char* xml = "<element/>";
@ -98,6 +105,15 @@ int example_2()
return doc.ErrorID();
}
/** @page Example-2 Parse an XML from char buffer
* @dontinclude ./xmltest.cpp
* Basic XML string parsing.
* The basic syntax to parse an XML for
* a char* and check for an error. (ErrorID()
* will return 0 for no error.)
* @skip example_2()
* @until }
*/
int example_3()
@ -122,6 +138,69 @@ int example_3()
return doc.ErrorID();
}
/** @page Example-3 Get information out of XML
@dontinclude ./xmltest.cpp
In this example, we navigate a simple XML
file, and read some interesting text. Note
that this is examlpe doesn't use error
checking; working code should check for null
pointers when walking an XML tree, or use
XMLHandle.
(The XML is an excerpt from "dream.xml").
@skip example_3()
@until </PLAY>";
The structure of the XML file is:
<ul>
<li>(declaration)</li>
<li>(dtd stuff)</li>
<li>Element "PLAY"</li>
<ul>
<li>Element "TITLE"</li>
<ul>
<li>Text "A Midsummer Night's Dream"</li>
</ul>
</ul>
</ul>
For this example, we want to print out the
title of the play. The text of the title (what
we want) is child of the "TITLE" element which
is a child of the "PLAY" element.
We want to skip the declaration and dtd, so the
method FirstChildElement() is a good choice. The
FirstChildElement() of the Document is the "PLAY"
Element, the FirstChildElement() of the "PLAY" Element
is the "TITLE" Element.
@until ( "TITLE" );
We can then use the convenience function GetText()
to get the title of the play.
@until title );
Text is just another Node in the XML DOM. And in
fact you should be a little cautious with it, as
text nodes can contain elements.
@verbatim
Consider: A Midsummer Night's <b>Dream</b>
@endverbatim
It is more correct to actually query the Text Node
if in doubt:
@until title );
Noting that here we use FirstChild() since we are
looking for XMLText, not an element, and ToText()
is a cast from a Node to a XMLText.
*/
bool example_4()
@ -150,6 +229,39 @@ bool example_4()
return !doc.Error() && ( v0 == v1 );
}
/** @page Example-4 Read attributes and text information.
@dontinclude ./xmltest.cpp
There are fundamentally 2 ways of writing a key-value
pair into an XML file. (Something that's always annoyed
me about XML.) Either by using attributes, or by writing
the key name into an element and the value into
the text node wrapped by the element. Both approaches
are illustrated in this example, which shows two ways
to encode the value "2" into the key "v":
@skip example_4()
@until "</information>";
TinyXML-2 has accessors for both approaches.
When using an attribute, you navigate to the XMLElement
with that attribute and use the QueryIntAttribute()
group of methods. (Also QueryFloatAttribute(), etc.)
@skip XMLElement* attributeApproachElement
@until &v0 );
When using the text approach, you need to navigate
down one more step to the XMLElement that contains
the text. Note the extra FirstChildElement( "v" )
in the code below. The value of the text can then
be safely queried with the QueryIntText() group
of methods. (Also QueryFloatText(), etc.)
@skip XMLElement* textApproachElement
@until &v1 );
*/
int main( int /*argc*/, const char ** /*argv*/ )

129
xmltest.h
View File

@ -1,129 +0,0 @@
// Purely doxygen documentation
// What follows is the docs for the examples.
// I'd like the docs to be just before the
// actual examples in xmltest.cpp, but I
// can't seem to get doxygen to do that. It
// would be a wonderful patch if anyone figures
// it out.
/** @page Example-1 Load an XML File
* @dontinclude ./xmltest.cpp
* Basic XML file loading.
* The basic syntax to load an XML file from
* disk and check for an error. (ErrorID()
* will return 0 for no error.)
* @skip example_1()
* @until }
*/
/** @page Example-2 Parse an XML from char buffer
* @dontinclude ./xmltest.cpp
* Basic XML string parsing.
* The basic syntax to parse an XML for
* a char* and check for an error. (ErrorID()
* will return 0 for no error.)
* @skip example_2()
* @until }
*/
/** @page Example-3 Get information out of XML
@dontinclude ./xmltest.cpp
In this example, we navigate a simple XML
file, and read some interesting text. Note
that this is examlpe doesn't use error
checking; working code should check for null
pointers when walking an XML tree, or use
XMLHandle.
(The XML is an excerpt from "dream.xml").
@skip example_3
@until </PLAY>";
The structure of the XML file is:
<ul>
<li>(declaration)</li>
<li>(dtd stuff)</li>
<li>Element "PLAY"</li>
<ul>
<li>Element "TITLE"</li>
<ul>
<li>Text "A Midsummer Night's Dream"</li>
</ul>
</ul>
</ul>
For this example, we want to print out the
title of the play. The text of the title (what
we want) is child of the "TITLE" element which
is a child of the "PLAY" element.
We want to skip the declaration and dtd, so the
method FirstChildElement() is a good choice. The
FirstChildElement() of the Document is the "PLAY"
Element, the FirstChildElement() of the "PLAY" Element
is the "TITLE" Element.
@until ( "TITLE" );
We can then use the convenience function GetText()
to get the title of the play.
@until title );
Text is just another Node in the XML DOM. And in
fact you should be a little cautious with it, as
text nodes can contain elements.
@verbatim
Consider: A Midsummer Night's <b>Dream</b>
@endverbatim
It is more correct to actually query the Text Node
if in doubt:
@until title );
Noting that here we use FirstChild() since we are
looking for XMLText, not an element, and ToText()
is a cast from a Node to a XMLText.
*/
/** @page Example-4 Read attributes and text information.
@dontinclude ./xmltest.cpp
There are fundamentally 2 ways of writing a key-value
pair into an XML file. (Something that's always annoyed
me about XML.) Either by using attributes, or by writing
the key name into an element and the value into
the text node wrapped by the element. Both approaches
are illustrated in this example, which shows two ways
to encode the value "2" into the key "v":
@skip example_4
@until "</information>";
TinyXML-2 has accessors for both approaches.
When using an attribute, you navigate to the XMLElement
with that attribute and use the QueryIntAttribute()
group of methods. (Also QueryFloatAttribute(), etc.)
@skip XMLElement* attributeApproachElement
@until &v0 );
When using the text approach, you need to navigate
down one more step to the XMLElement that contains
the text. Note the extra FirstChildElement( "v" )
in the code below. The value of the text can then
be safely queried with the QueryIntText() group
of methods. (Also QueryFloatText(), etc.)
@skip XMLElement* textApproachElement
@until &v1 );
*/