From 4504aab21db2c56de92f8a81990182ff18eb6036 Mon Sep 17 00:00:00 2001 From: Martinsh Shaiters Date: Wed, 16 Jan 2013 00:54:58 +0200 Subject: [PATCH 1/3] Upgrades dox to Doxyfile version 1.8.3 Upgrade removes deprecated options HTML_ALIGN_MEMBERS, SHOW_DIRECTORIES and USE_INLINE_TREES. These are deprecated since Doxygen release 1.8.1 (2012-05-09) [http://www.stack.nl/~dimitri/doxygen/changelog.html#1.8.1]. --- dox | 176 +++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 121 insertions(+), 55 deletions(-) diff --git a/dox b/dox index d3a6297..650b9bd 100755 --- a/dox +++ b/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.h \ + 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 = + #--------------------------------------------------------------------------- # 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. From bbad12a9221b0c2331fcdbbcb1ccd3d692285fc2 Mon Sep 17 00:00:00 2001 From: Martinsh Shaiters Date: Wed, 16 Jan 2013 01:55:39 +0200 Subject: [PATCH 2/3] Sets readme.md to be used as MainPage for generated documentation --- dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dox b/dox index 650b9bd..7dc93df 100755 --- a/dox +++ b/dox @@ -793,7 +793,7 @@ FILTER_SOURCE_PATTERNS = # 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 = +USE_MDFILE_AS_MAINPAGE = readme.md #--------------------------------------------------------------------------- # configuration options related to source browsing From c9c8b77d87581cdc2144e9bb6649d50fa25c9ce4 Mon Sep 17 00:00:00 2001 From: Martinsh Shaiters Date: Wed, 16 Jan 2013 02:08:19 +0200 Subject: [PATCH 3/3] Moves example documentation from xmltest.h to xmltest.cpp --- dox | 2 +- xmltest.cpp | 118 +++++++++++++++++++++++++++++++++++++++++++++-- xmltest.h | 129 ---------------------------------------------------- 3 files changed, 116 insertions(+), 133 deletions(-) delete mode 100755 xmltest.h diff --git a/dox b/dox index 7dc93df..ad8dfd0 100755 --- a/dox +++ b/dox @@ -669,7 +669,7 @@ WARN_LOGFILE = # with spaces. INPUT = tinyxml2.h \ - xmltest.h \ + xmltest.cpp \ readme.md # This tag can be used to specify the character encoding of the source files diff --git a/xmltest.cpp b/xmltest.cpp index 6944ca2..8a13382 100644 --- a/xmltest.cpp +++ b/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 = ""; @@ -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 "; + + The structure of the XML file is: + +
    +
  • (declaration)
    • +
  • (dtd stuff)
    • +
  • Element "PLAY"
    • +
      +
    • Element "TITLE"
      • +
        +
      • Text "A Midsummer Night's Dream"
        • +
      +
    +
+ + 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 Dream + @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 ""; + + 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*/ ) diff --git a/xmltest.h b/xmltest.h deleted file mode 100755 index 4dd0a51..0000000 --- a/xmltest.h +++ /dev/null @@ -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 "; - - The structure of the XML file is: - -
    -
  • (declaration)
    • -
  • (dtd stuff)
    • -
  • Element "PLAY"
    • -
      -
    • Element "TITLE"
      • -
        -
      • Text "A Midsummer Night's Dream"
        • -
      -
    -
- - 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 Dream - @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 ""; - - 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 ); -*/ -