Clarify QDomProcessingInstruction docs regarding XML declaration

The documentation now explicitly explains that the XML declaration is
not a processing instruction according to the XML 1.0 Specification and
the W3C DOM Level 1/2 Core specifications. It advises against using
createProcessingInstruction() to insert an XML declaration and
recommends QXmlStreamWriter.
This clarification aims to reduce confusion caused by the similar syntax
of processing instructions and the XML declaration.

Fixes: QTBUG-21166
Pick-to: 6.9 6.8 6.5
Change-Id: I630e0e73bc8e4b6f145cb1e771a0a6fec54543cf
Reviewed-by: Safiyyah Moosa <[email protected]>
Reviewed-by: Edward Welbourne <[email protected]>

1 files changed, 11 insertions, 3 deletions

diff --git a/src/xml/dom/qdom.cpp b/src/xml/dom/qdom.cpp
index 7bfe6cd5cc7..f3c7e2d9938 100644
--- a/src/xml/dom/qdom.cpp
+++ b/src/xml/dom/qdom.cpp
@@ -5703,9 +5703,17 @@ void QDomProcessingInstructionPrivate::save(QTextStream& s, int, int) const
     not a processing instruction; among other differences, it cannot be
     inserted into a document anywhere but on the first line.
 
-    Do not use this function to create an xml declaration, since although it
-    has the same syntax as a processing instruction, it isn't, and might not
-    be treated by QDom as such.
+    \note Do not use this function to create an XML declaration. Although the
+    XML declaration shares the same syntax as a processing instruction, it
+    is not one. According to the
+    \l{https://www.w3.org/TR/xml/#sec-prolog-dtd}{XML 1.0 Specification} and the
+    \l{https://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-1590626202}{W3C DOM Structure Model},
+    the XML declaration is part of the document prolog and not part of the
+    DOM tree - meaning it should not be represented as a DOM node and cannot be
+    created or inserted via the DOM API.
+    If you need to generate a well-formed XML document that includes an XML
+    declaration, use QXmlStreamWriter, which provides proper support for
+    writing the declaration through \l {QXmlStreamWriter::}{writeStartDocument}.
 
     The content of the processing instruction is retrieved with data()
     and set with setData(). The processing instruction's target is