QDoc manual: improve description of argument handling

Move the important block up, so that people notice in the first time
they read the docs. Add a sentence to describe the point of enclosing
arguments in curly braces.

Fixes: QTBUG-109734
Change-Id: I245ff686a43c6fd443afdf98a28cd9564e492ed7
Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>
(cherry picked from commit 47549facf70d8edcb9428980600076087a9a2cdb)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

1 files changed, 6 insertions, 5 deletions

diff --git a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
index dee95f7e1..b8a77c47e 100644
--- a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -3756,7 +3756,12 @@
     are used for injecting strings into the included content. To inject a
     string to a specific location in the content, add a backslash followed
     by a digit (1..9). The digits correspond with the order of the argument
-    list.
+    list. Enclose arguments in curly braces to ensure that QDoc renders the
+    entire argument, including possible whitespace characters, as you expect.
+
+    \important Each additional argument (including the snippet ID) must be
+               enclosed in braces. If you want to include the entire file,
+               use an empty snippet ID: \c {{}}.
 
     For example, given the following snippet in a file \c includes.qdocinc:
 
@@ -3778,10 +3783,6 @@
     \uicontrol Enable.
     \endquotation
 
-    \important Each additional argument (including the snippet ID) must be
-               enclosed in braces. If you want to include the entire file,
-               use an empty snippet ID: \c {{}}.
-
     \target meta-command
     \section1 \\meta