Merge pull request #91 from martinsh-shaiters/doxyfix

Example documentation moved to xmltest.cpp

dox

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

xmltest.cpp

@@ -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*/ )

xmltest.h

@@ -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 );
-*/
-