qdoc: Allow parameters for \code, \qml, \js, and \badcode commands

Allow optional parameters for commands that enclose code snippets.
This is intended for replacing simple strings within the snippet,
typically using a macro that extends to certain parameter(s).

Within the snippet, the parameter locations are marked similarly
to .qdocconf macro parameters:

\code foo bar
\1+\2=\1\2
\encode

Renders "foo+bar=foobar"

A code snippet parameter cannot contain spaces, as space is used
as a delimiter. If no parameters are passed, the snippet is
rendered as-is.

Task-number: QTBUG-67818
Change-Id: I500e6b1a9095c9c55f47c8d75951792f31745545
Reviewed-by: Martin Smith <martin.smith@qt.io>

2 files changed, 59 insertions, 7 deletions

diff --git a/src/qdoc/doc.cpp b/src/qdoc/doc.cpp
index 80e440086..9e998fe87 100644
--- a/src/qdoc/doc.cpp
+++ b/src/qdoc/doc.cpp
@@ -480,7 +480,7 @@ private:
     QString getRestOfLine();
     QString getMetaCommandArgument(const QString &cmdStr);
     QString getUntilEnd(int cmd);
-    QString getCode(int cmd, CodeMarker *marker);
+    QString getCode(int cmd, CodeMarker *marker, const QString &argStr = QString());
     QString getUnmarkedCode(int cmd);
 
     bool isBlankLine();
@@ -627,7 +627,7 @@ void DocParser::parse(const QString& source,
                     break;
                 case CMD_BADCODE:
                     leavePara();
-                    append(Atom::CodeBad,getCode(CMD_BADCODE, marker));
+                    append(Atom::CodeBad, getCode(CMD_BADCODE, marker, getMetaCommandArgument(cmdStr)));
                     break;
                 case CMD_BR:
                     enterPara();
@@ -655,18 +655,22 @@ void DocParser::parse(const QString& source,
                     break;
                 case CMD_CODE:
                     leavePara();
-                    append(Atom::Code, getCode(CMD_CODE, 0));
+                    append(Atom::Code, getCode(CMD_CODE, 0, getMetaCommandArgument(cmdStr)));
                     break;
                 case CMD_QML:
                     leavePara();
-                    append(Atom::Qml, getCode(CMD_QML, CodeMarker::markerForLanguage(QLatin1String("QML"))));
+                    append(Atom::Qml, getCode(CMD_QML,
+                                              CodeMarker::markerForLanguage(QLatin1String("QML")),
+                                              getMetaCommandArgument(cmdStr)));
                     break;
                 case CMD_QMLTEXT:
                     append(Atom::QmlText);
                     break;
                 case CMD_JS:
                     leavePara();
-                    append(Atom::JavaScript, getCode(CMD_JS, CodeMarker::markerForLanguage(QLatin1String("JavaScript"))));
+                    append(Atom::JavaScript, getCode(CMD_JS,
+                                                     CodeMarker::markerForLanguage(QLatin1String("JavaScript")),
+                                                     getMetaCommandArgument(cmdStr)));
                     break;
                 case CMD_DIV:
                     leavePara();
@@ -2541,9 +2545,27 @@ QString DocParser::getUntilEnd(int cmd)
     return t;
 }
 
-QString DocParser::getCode(int cmd, CodeMarker *marker)
+QString DocParser::getCode(int cmd, CodeMarker *marker, const QString &argStr)
 {
     QString code = untabifyEtc(getUntilEnd(cmd));
+
+    if (!argStr.isEmpty()) {
+        QStringList args = argStr.split(" ", QString::SkipEmptyParts);
+        int paramNo, j = 0;
+        while (j < code.size()) {
+            if (code[j] == '\\'
+                 && j < code.size() - 1
+                 && (paramNo = code[j + 1].digitValue()) >= 1
+                 && paramNo <= args.size()) {
+                QString p = args[paramNo - 1];
+                code.replace(j, 2, p);
+                j += qMin(1, p.size());
+            } else {
+                ++j;
+            }
+        }
+    }
+
     int indent = indentLevel(code);
     code = unindent(indent, code);
     if (!marker)
diff --git a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
index ded656eed..8ba6efa05 100644
--- a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -993,7 +993,32 @@
 
     Other QDoc commands are disabled within \\code... \\endcode, and
     the special character '\\' is accepted and rendered like the rest
-    of the code.
+    of the code, unless it is followed by a digit and parameters were
+    passed to \\code.
+
+    \section2 Code snippet parameters
+
+    Since QDoc version 5.12, \\code command accepts also optional
+    parameters. Parameters are useful for injecting simple
+    strings into the code snippet. To inject a string to a specific
+    location in the snippet, add a backslash followed by a digit (1..8).
+    The digits correspond with the order of the argument list, where
+    arguments are separated by spaces.
+
+    For example:
+
+    \code
+    / *!
+    \code * hello
+    /\1 \2 \1/
+    \ endcode
+    * /
+    \endcode
+
+    For the above snippet, QDoc renders the word \e hello enclosed in
+    a C-style comment.
+
+    \section2 Including code from external files
 
     To include code snippets from an external file, use the
     \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
@@ -1018,6 +1043,8 @@
     instructions, shell scripts or any other content that is not in a Qt
     language, but should still be styled similarly to a \\code paragraph.
 
+    Like \\code, \\badcode accepts also optional parameters.
+
     \target newcode-command
     \section1 \\newcode
 
@@ -1118,6 +1145,9 @@
             }
         }
     \endqml
+
+    Like the \l{code-command}{\\code} command, \\qml accepts optional
+    parameters.
 */