From 64fd9edb2c5e935ffc58ce12434b582e32d4e93b Mon Sep 17 00:00:00 2001 From: Magdalena Stojek Date: Wed, 26 Mar 2025 07:34:01 +0100 Subject: [PATCH] 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.8 6.5 Change-Id: I630e0e73bc8e4b6f145cb1e771a0a6fec54543cf Reviewed-by: Safiyyah Moosa Reviewed-by: Edward Welbourne (cherry picked from commit d2258328e39ab8695e8034fe85cec7a18884f6d2) Reviewed-by: Qt Cherry-pick Bot --- src/xml/dom/qdom.cpp | 14 +++++++++++--- 1 file 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