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