Added proper examples, integrated them into xmltest, and make them part of the build.
diff --git a/dox b/dox
index 108c6e2..9568fa9 100755
--- a/dox
+++ b/dox
@@ -32,7 +32,7 @@
# This could be handy for archiving the generated documentation or
# if some version control system is used.
-PROJECT_NUMBER = 0.9.2
+PROJECT_NUMBER = 0.9.2
# 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
@@ -721,7 +721,7 @@
# directories that contain example code fragments that are included (see
# the \include command).
-EXAMPLE_PATH =
+EXAMPLE_PATH = .
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
@@ -1040,7 +1040,7 @@
# The TOC_EXPAND flag can be set to YES to add extra items for group members
# to the contents of the HTML help documentation and to the tree view.
-TOC_EXPAND = NO
+TOC_EXPAND = YES
# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and
# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated
diff --git a/readme.txt b/readme.txt
index 4fc5d9c..ec2d015 100755
--- a/readme.txt
+++ b/readme.txt
@@ -8,6 +8,12 @@
The master is hosted on github:
github.com/leethomason/tinyxml2
+The online HTML version of these docs:
+http://grinninglizard.com/tinyxml2docs/index.html
+
+Where examples are in the "related pages" tab:
+http://grinninglizard.com/tinyxml2docs/pages.html
+
<h2> What it does. </h2>
In brief, TinyXML parses an XML document, and builds from that a
diff --git a/tinyxml2.h b/tinyxml2.h
index ae20e18..121fe03 100644
--- a/tinyxml2.h
+++ b/tinyxml2.h
@@ -39,6 +39,7 @@
#include <memory.h> // Needed by mac.
#endif
+
/*
TODO: add 'lastAttribute' for faster parsing.
TODO: intern strings instead of allocation.
@@ -1251,5 +1252,96 @@
} // tinyxml2
+// 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.
+*/
#endif // TINYXML2_INCLUDED
diff --git a/xmltest.cpp b/xmltest.cpp
index 20e3fa9..bb5bdfb 100644
--- a/xmltest.cpp
+++ b/xmltest.cpp
@@ -71,6 +71,51 @@
}
+// Comments in the header. (Don't know how to get Doxygen to read comments in this file.)
+int example_1()
+{
+ XMLDocument doc;
+ doc.LoadFile( "dream.xml" );
+
+ return doc.ErrorID();
+}
+
+
+// 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/>";
+ XMLDocument doc;
+ doc.Parse( xml );
+
+ return doc.ErrorID();
+}
+
+
+int example_3()
+{
+ static const char* xml =
+ "<?xml version=\"1.0\"?>"
+ "<!DOCTYPE PLAY SYSTEM \"play.dtd\">"
+ "<PLAY>"
+ "<TITLE>A Midsummer Night's Dream</TITLE>"
+ "</PLAY>";
+
+ XMLDocument doc;
+ doc.Parse( xml );
+
+ XMLElement* titleElement = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" );
+ const char* title = titleElement->GetText();
+ printf( "Name of play (1): %s\n", title );
+
+ XMLText* textNode = titleElement->FirstChild()->ToText();
+ title = textNode->Value();
+ printf( "Name of play (2): %s\n", title );
+
+ return doc.ErrorID();
+}
+
+
int main( int /*argc*/, const char ** /*argv*/ )
{
#if defined( _MSC_VER ) && defined( DEBUG )
@@ -100,31 +145,11 @@
#pragma warning ( pop )
#endif
- /* ------ Example 1: Load and parse an XML file. ---- */
- {
- XMLDocument doc;
- doc.LoadFile( "dream.xml" );
- }
-
- /* ------ Example 2: Lookup information. ---- */
- {
- XMLDocument doc;
- doc.LoadFile( "dream.xml" );
+ XMLTest( "Example-1", 0, example_1() );
+ XMLTest( "Example-2", 0, example_2() );
+ XMLTest( "Example-3", 0, example_3() );
- // Structure of the XML file:
- // - Element "PLAY" the root Element
- // - - Element "TITLE" child of the root PLAY Element
- // - - - Text child of the TITLE Element
-
- // Navigate to the title, using the convenience function, with a dangerous lack of error checking.
- const char* title = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->GetText();
- printf( "Name of play (1): %s\n", title );
-
- // Text is just another Node to TinyXML-2. The more general way to get to the XMLText:
- XMLText* textNode = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->FirstChild()->ToText();
- title = textNode->Value();
- printf( "Name of play (2): %s\n", title );
- }
+ /* ------ Example 2: Lookup information. ---- */
{
static const char* test[] = { "<element />",