Doc: Make snippets XML compilable

Task-number: QTBUG-84459 Change-Id: I143a8b8869f7cb8547f1898831d0d6e86b7ac35d Reviewed-by: Paul Wicking <paul.wicking@qt.io>
author: Nico Vertriest <nico.vertriest@qt.io> 2020-07-01 08:58:05 +0200
committer: Paul Wicking <paul.wicking@qt.io> 2020-09-01 06:11:56 +0200
commit: 2c7d46727ed1de7c8233f0520cc40e9e6ce72fac (patch)
tree: 2af4fdeab40b525d1a8abfdc09e60d1ac9ba4f8e /src/xml
parent: 1ca85a2fd14d3838df165fbf0ccf898a340743cf (diff)
4 files changed, 160 insertions, 83 deletions
diff --git a/src/xml/doc/snippets/code/src_xml_dom_qdom.cpp b/src/xml/doc/snippets/code/src_xml_dom_qdom.cpp
index f7d81f676f..cc5d7c0b13 100644
--- a/src/xml/doc/snippets/code/src_xml_dom_qdom.cpp
+++ b/src/xml/doc/snippets/code/src_xml_dom_qdom.cpp
@@ -47,99 +47,83 @@
 ** $QT_END_LICENSE$
 **
 ****************************************************************************/
-
+#include <iostream>
+#include <cstring>
+#include <QFile>
+#include <QDomDocument>
+#include <QDomImplementation>
+
+void NodeElements();
+void DomText();
+void FirstElement();
+void FileContent();
+void DocAppend();
+void XML_snippet_main();
+
+using namespace std;
 //! [0]
+void XML_snippet_main()
+{
 QDomDocument doc;
 QDomImplementation impl;
-
 // This will create the element, but the resulting XML document will
 // be invalid, because '~' is not a valid character in a tag name.
-impl.setInvalidDataPolicy(QDomImplementation::AcceptInvalidData);
+impl.setInvalidDataPolicy(QDomImplementation::AcceptInvalidChars);
 QDomElement elt1 = doc.createElement("foo~bar");
 
 // This will create an element with the tag name "foobar".
-impl.setInvalidDataPolicy(QDomImplementation::DropInvalidData);
+impl.setInvalidDataPolicy(QDomImplementation::DropInvalidChars);
 QDomElement elt2 = doc.createElement("foo~bar");
 
 // This will create a null element.
 impl.setInvalidDataPolicy(QDomImplementation::ReturnNullNode);
 QDomElement elt3 = doc.createElement("foo~bar");
+}
 //! [0]
 
-
+void NodeElements()
+{
 //! [1]
 QDomDocument d;
+QString someXML;
+
 d.setContent(someXML);
 QDomNode n = d.firstChild();
 while (!n.isNull()) {
     if (n.isElement()) {
         QDomElement e = n.toElement();
-        cout << "Element name: " << e.tagName() << Qt::endl;
+        cout << "Element name: " << qPrintable(e.tagName()) << '\n';
         break;
     }
     n = n.nextSibling();
 }
 //! [1]
 
-
 //! [2]
 QDomDocument document;
 QDomElement element1 = document.documentElement();
 QDomElement element2 = element1;
 //! [2]
 
-
 //! [3]
 QDomElement element3 = document.createElement("MyElement");
 QDomElement element4 = document.createElement("MyElement");
 //! [3]
 
-
-//! [4]
-<body>
-<h1>Heading</h1>
-<p>Hello <b>you</b></p>
-</body>
-//! [4]
-
-
-//! [5]
-<h1>Heading</h1>
-<p>The text...</p>
-<h2>Next heading</h2>
-//! [5]
-
-
-//! [6]
-<h1>Heading</h1>
-<p>The text...</p>
-<h2>Next heading</h2>
-//! [6]
-
-
-//! [7]
-<link href="http://qt-project.org" color="red" />
-//! [7]
-
-
 //! [8]
-QDomElement e = //...
+QDomElement e;
 //...
 QDomAttr a = e.attributeNode("href");
-cout << a.value() << Qt::endl;                // prints "http://qt-project.org"
+cout << qPrintable(a.value()) << '\n';   // prints "http://qt-project.org"
 a.setValue("http://qt-project.org/doc"); // change the node's attribute
 QDomAttr a2 = e.attributeNode("href");
-cout << a2.value() << Qt::endl;               // prints "http://qt-project.org/doc"
+cout << qPrintable(a2.value()) << '\n';  // prints "http://qt-project.org/doc"
 //! [8]
+}
 
-
-//! [9]
-QDomElement e = //...
-//...
-QString s = e.text()
-//! [9]
-
-
+void DomText()
+{
+QDomDocument doc;
 //! [10]
 QString text;
 QDomElement element = doc.documentElement();
@@ -151,37 +135,21 @@ for(QDomNode n = element.firstChild(); !n.isNull(); n = n.nextSibling())
 }
 //! [10]
 
-
+}
+void FirstElement()
+{
 //! [11]
-QDomDocument doc = // ...
+QDomDocument doc;
 QDomElement root = doc.firstChildElement("database");
 QDomElement elt = root.firstChildElement("entry");
 for (; !elt.isNull(); elt = elt.nextSiblingElement("entry")) {
     // ...
 }
 //! [11]
+}
 
-
-//! [12]
-<img src="myimg.png">
-//! [12]
-
-
-//! [13]
-<h1>Hello <b>Qt</b> <![CDATA[<xml is cool>]]></h1>
-//! [13]
-
-
-//! [14]
-Hello Qt <xml is cool>
-//! [14]
-
-
-//! [15]
-<!-- this is a comment -->
-//! [15]
-
-
+void FileContent()
+{
 //! [16]
 QDomDocument doc("mydocument");
 QFile file("mydocument.xml");
@@ -201,7 +169,7 @@ QDomNode n = docElem.firstChild();
 while(!n.isNull()) {
     QDomElement e = n.toElement(); // try to convert the node to an element.
     if(!e.isNull()) {
-        cout << qPrintable(e.tagName()) << Qt::endl; // the node really is an element.
+        cout << qPrintable(e.tagName()) << '\n'; // the node really is an element.
     }
     n = n.nextSibling();
 }
@@ -211,10 +179,12 @@ QDomElement elem = doc.createElement("img");
 elem.setAttribute("src", "myimage.png");
 docElem.appendChild(elem);
 //! [16]
+}
 
-
+void DocAppend()
+{
 //! [17]
-QDomDocument doc("MyML");
+QDomDocument doc;
 QDomElement root = doc.createElement("MyML");
 doc.appendChild(root);
 
@@ -226,3 +196,4 @@ tag.appendChild(t);
 
 QString xml = doc.toString();
 //! [17]
+}
diff --git a/src/xml/doc/snippets/code/src_xml_dom_qdom_snippet.cpp b/src/xml/doc/snippets/code/src_xml_dom_qdom_snippet.cpp
new file mode 100644
index 0000000000..233cdac8d7
--- /dev/null
+++ b/src/xml/doc/snippets/code/src_xml_dom_qdom_snippet.cpp
@@ -0,0 +1,102 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+//! [4]
+<body>
+<h1>Heading</h1>
+<p>Hello <b>you</b></p>
+</body>
+//! [4]
+
+//! [5]
+<h1>Heading</h1>
+<p>The text...</p>
+<h2>Next heading</h2>
+//! [5]
+
+//! [6]
+<h1>Heading</h1>
+<p>The text...</p>
+<h2>Next heading</h2>
+//! [6]
+
+//! [7]
+<link href="http://qt-project.org" color="red" />
+//! [7]
+
+//! [9]
+QDomElement e = //...
+//...
+QString s = e.text()
+//! [9]
+
+//! [11]
+QDomDocument doc = // ...
+QDomElement root = doc.firstChildElement("database");
+QDomElement elt = root.firstChildElement("entry");
+for (; !elt.isNull(); elt = elt.nextSiblingElement("entry")) {
+    // ...
+}
+//! [11]
+
+//! [12]
+<img src="myimg.png">
+//! [12]
+
+//! [13]
+<h1>Hello <b>Qt</b> <![CDATA[<xml is cool>]]></h1>
+//! [13]
+
+//! [14]
+Hello Qt <xml is cool>
+//! [14]
+
+//! [15]
+<!-- this is a comment -->
+//! [15]
diff --git a/src/xml/doc/snippets/snippets.pro b/src/xml/doc/snippets/snippets.pro
index df72b89d98..2de9693561 100644
--- a/src/xml/doc/snippets/snippets.pro
+++ b/src/xml/doc/snippets/snippets.pro
@@ -7,3 +7,7 @@ QT += xml
 #! [qmake_use]
 
 load(qt_common)
+
+QT += core xml
+
+SOURCES += code/src_xml_dom_qdom.cpp
diff --git a/src/xml/dom/qdom.cpp b/src/xml/dom/qdom.cpp
index e6c21a3332..0856a83a52 100644
--- a/src/xml/dom/qdom.cpp
+++ b/src/xml/dom/qdom.cpp
@@ -1723,7 +1723,7 @@ QDomNode QDomNode::parentNode() const
 
     For example, if the XML document looks like this:
 
-    \snippet code/src_xml_dom_qdom.cpp 4
+    \snippet code/src_xml_dom_qdom_snippet.cpp 4
 
     Then the list of child nodes for the "body"-element will contain
     the node created by the &lt;h1&gt; tag and the node created by the
@@ -1775,7 +1775,7 @@ QDomNode QDomNode::lastChild() const
 
     For example, if you have XML like this:
 
-    \snippet code/src_xml_dom_qdom.cpp 5
+    \snippet code/src_xml_dom_qdom_snippet.cpp 5
 
     and this QDomNode represents the &lt;p&gt; tag, previousSibling()
     will return the node representing the &lt;h1&gt; tag.
@@ -1795,7 +1795,7 @@ QDomNode QDomNode::previousSibling() const
 
     If you have XML like this:
 
-    \snippet code/src_xml_dom_qdom.cpp 6
+    \snippet code/src_xml_dom_qdom_snippet.cpp 6
 
     and this QDomNode represents the <p> tag, nextSibling() will
     return the node representing the <h2> tag.
@@ -3745,7 +3745,7 @@ void QDomAttrPrivate::save(QTextStream& s, int, int) const
     For example, the following piece of XML produces an element with
     no children, but two attributes:
 
-    \snippet code/src_xml_dom_qdom.cpp 7
+    \snippet code/src_xml_dom_qdom_snippet.cpp 7
 
     You can access the attributes of an element with code like this:
 
@@ -4159,7 +4159,7 @@ void QDomElementPrivate::save(QTextStream& s, int depth, int indent) const
 
     If you want to access the text of a node use text(), e.g.
 
-    \snippet code/src_xml_dom_qdom.cpp 9
+    \snippet code/src_xml_dom_qdom_snippet.cpp 9
 
     The text() function operates recursively to find the text (since
     not all elements contain text). If you want to find all the text
@@ -4181,7 +4181,7 @@ void QDomElementPrivate::save(QTextStream& s, int depth, int indent) const
     nextSiblingElement() and previousSiblingElement(). For example, to iterate over all
     child elements called "entry" in a root element called "database", you can use:
 
-    \snippet code/src_xml_dom_qdom.cpp 11
+    \snippet code/src_xml_dom_qdom_snippet.cpp 11
 
    For further information about the Document Object Model see
     \l{W3C DOM Level 1}{Level 1} and
@@ -4248,7 +4248,7 @@ void QDomElement::setTagName(const QString& name)
 /*!
     Returns the tag name of this element. For an XML element like this:
 
-    \snippet code/src_xml_dom_qdom.cpp 12
+    \snippet code/src_xml_dom_qdom_snippet.cpp 12
 
     the tagname would return "img".
 
@@ -4618,12 +4618,12 @@ bool QDomElement::hasAttributeNS(const QString& nsURI, const QString& localName)
     Returns the element's text or an empty string.
 
     Example:
-    \snippet code/src_xml_dom_qdom.cpp 13
+    \snippet code/src_xml_dom_qdom_snippet.cpp 13
 
     The function text() of the QDomElement for the \c{<h1>} tag,
     will return the following text:
 
-    \snippet code/src_xml_dom_qdom.cpp 14
+    \snippet code/src_xml_dom_qdom_snippet.cpp 14
 
     Comments are ignored by this function. It only evaluates QDomText
     and QDomCDATASection objects.
@@ -4830,7 +4830,7 @@ void QDomCommentPrivate::save(QTextStream& s, int depth, int indent) const
 
     A comment in the parsed XML such as this:
 
-    \snippet code/src_xml_dom_qdom.cpp 15
+    \snippet code/src_xml_dom_qdom_snippet.cpp 15
 
     is represented by QDomComment objects in the parsed Dom tree.
author	Nico Vertriest <nico.vertriest@qt.io>	2020-07-01 08:58:05 +0200
committer	Paul Wicking <paul.wicking@qt.io>	2020-09-01 06:11:56 +0200
commit	2c7d46727ed1de7c8233f0520cc40e9e6ce72fac (patch)
tree	2af4fdeab40b525d1a8abfdc09e60d1ac9ba4f8e /src/xml
parent	1ca85a2fd14d3838df165fbf0ccf898a340743cf (diff)