From b968ed6bc09d363f96ab6761f88fde790f7f09b1 Mon Sep 17 00:00:00 2001
From: Jaishree Vyas <Jaishree.Vyas@qt.io>
Date: Wed, 1 Mar 2023 11:59:11 +0100
Subject: qdoc: Add \details command

The command \details generates a collapsible <details>
element with a <summary> to control the hidden/visible
state.

The idea behind this is to provide more information with
less text on our main pages.

For output formats other than HTML, the details are
rendered as a normal paragraph and the summary string
is ignored.

Pick-to: 6.5
Change-Id: Id5daddd4854f22b9ceaa9a55b98af94a1ba06039
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
---
 src/qdoc/qdoc/atom.cpp                             |  4 +++
 src/qdoc/qdoc/atom.h                               |  2 ++
 src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc      | 40 ++++++++++++++++++++++
 src/qdoc/qdoc/docbookgenerator.cpp                 |  3 ++
 src/qdoc/qdoc/docparser.cpp                        | 19 +++++++++-
 src/qdoc/qdoc/htmlgenerator.cpp                    | 10 ++++++
 .../docbook/qdoctests-qdocfileoutput.xml           |  3 ++
 .../html/qdoctests-qdocfileoutput.webxml           |  2 ++
 .../expected_output/qdoctests-qdocfileoutput.html  |  6 ++++
 .../tocbreadcrumbs/qdoctests-qdocfileoutput.html   |  6 ++++
 .../qdoctests-outputfromqdocfiles.qdoc             |  4 +++
 11 files changed, 98 insertions(+), 1 deletion(-)

diff --git a/src/qdoc/qdoc/atom.cpp b/src/qdoc/qdoc/atom.cpp
index 6b895769f..080a8fddd 100644
--- a/src/qdoc/qdoc/atom.cpp
+++ b/src/qdoc/qdoc/atom.cpp
@@ -50,6 +50,8 @@ QT_BEGIN_NAMESPACE
   \value CodeBad
   \value CodeQuoteArgument
   \value CodeQuoteCommand
+  \value DetailsLeft
+  \value DetailsRight
   \value DivLeft
   \value DivRight
   \value ExampleFileLink
@@ -130,6 +132,8 @@ static const struct
              { "CodeBad", Atom::CodeBad },
              { "CodeQuoteArgument", Atom::CodeQuoteArgument },
              { "CodeQuoteCommand", Atom::CodeQuoteCommand },
+             { "DetailsLeft", Atom::DetailsLeft },
+             { "DetailsRight", Atom::DetailsRight },
              { "DivLeft", Atom::DivLeft },
              { "DivRight", Atom::DivRight },
              { "ExampleFileLink", Atom::ExampleFileLink },
diff --git a/src/qdoc/qdoc/atom.h b/src/qdoc/qdoc/atom.h
index ba453254b..3e642a6dd 100644
--- a/src/qdoc/qdoc/atom.h
+++ b/src/qdoc/qdoc/atom.h
@@ -31,6 +31,8 @@ public:
         CodeBad,
         CodeQuoteArgument,
         CodeQuoteCommand,
+        DetailsLeft,
+        DetailsRight,
         DivLeft,
         DivRight,
         ExampleFileLink,
diff --git a/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc
index 04d9f7cc3..714db3664 100644
--- a/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -173,6 +173,46 @@
 
     See also \l {tt-command} {\\tt} and \l {code-command} {\\code}.
 
+    \target details-command
+    \section1 \\details
+
+    The \\details and \\enddetails commands generates a collapsible <details>
+    element with a <summary> to control the hidden/visible state.
+
+    When generating HTML output, use the \\details and \\enddetails commands to
+    generate a collapsible \c{<details>} HTML element. The command takes an
+    optional summary string enclosed in curly braces. This optional argument
+    specifies a visible heading for the details.
+
+    For example, with the following input:
+    \badcode *
+        /\1!
+            \details {QDoc details}
+              \note You're looking at detailed information.
+            \enddetails
+        \1/
+    \endcode
+
+    If QDoc is generating HTML, it will translate these commands to:
+
+    \badcode
+    <summary>QDoc details</summary><div class="admonition note"><p><b>Note: </b>You're looking at detailed information.</p></div>
+    \endcode
+
+    QDoc renders this as:
+
+    \raw HTML
+        <details>
+        <summary>QDoc details</summary>
+        <div class="admonition note">
+        <p><b>Note: </b>You're looking at detailed information.</p>
+        </div>
+        </details>
+    \endraw
+
+    For any other output format, QDoc generates the contents as a normal paragraph,
+    ignoring the summary string.
+
     \target div-command
     \section1 \\div
 
diff --git a/src/qdoc/qdoc/docbookgenerator.cpp b/src/qdoc/qdoc/docbookgenerator.cpp
index b849e5453..cc75cac07 100644
--- a/src/qdoc/qdoc/docbookgenerator.cpp
+++ b/src/qdoc/qdoc/docbookgenerator.cpp
@@ -341,6 +341,9 @@ qsizetype DocBookGenerator::generateAtom(const Atom *atom, const Node *relative)
         m_writer->writeEndElement(); // programlisting
         newLine();
         break;
+    case Atom::DetailsLeft:
+    case Atom::DetailsRight:
+        break;
     case Atom::DivLeft:
     case Atom::DivRight:
         break;
diff --git a/src/qdoc/qdoc/docparser.cpp b/src/qdoc/qdoc/docparser.cpp
index c638cde4e..6702d8ed2 100644
--- a/src/qdoc/qdoc/docparser.cpp
+++ b/src/qdoc/qdoc/docparser.cpp
@@ -36,11 +36,13 @@ enum {
     CMD_CAPTION,
     CMD_CODE,
     CMD_CODELINE,
+    CMD_DETAILS,
     CMD_DIV,
     CMD_DOTS,
     CMD_E,
     CMD_ELSE,
     CMD_ENDCODE,
+    CMD_ENDDETAILS,
     CMD_ENDDIV,
     CMD_ENDFOOTNOTE,
     CMD_ENDIF,
@@ -136,11 +138,13 @@ static struct
              { "caption", CMD_CAPTION },
              { "code", CMD_CODE },
              { "codeline", CMD_CODELINE },
+             { "details", CMD_DETAILS },
              { "div", CMD_DIV },
              { "dots", CMD_DOTS },
              { "e", CMD_E },
              { "else", CMD_ELSE },
              { "endcode", CMD_ENDCODE },
+             { "enddetails", CMD_ENDDETAILS },
              { "enddiv", CMD_ENDDIV },
              { "endfootnote", CMD_ENDFOOTNOTE },
              { "endif", CMD_ENDIF },
@@ -382,6 +386,16 @@ void DocParser::parse(const QString &source, DocPrivate *docPrivate,
                            getCode(CMD_QML, CodeMarker::markerForLanguage(QLatin1String("QML")),
                                    getMetaCommandArgument(cmdStr)));
                     break;
+                case CMD_DETAILS:
+                    leavePara();
+                    append(Atom::DetailsLeft, getArgument());
+                    m_openedCommands.push(cmd);
+                    break;
+                case CMD_ENDDETAILS:
+                    leavePara();
+                    append(Atom::DetailsRight);
+                    closeCommand(cmd);
+                    break;
                 case CMD_DIV:
                     leavePara();
                     p1 = getArgument(true);
@@ -1749,7 +1763,8 @@ void DocParser::enterPara(Atom::AtomType leftType, Atom::AtomType rightType, con
     if (m_paragraphState == OutsideParagraph) {
 
         if ((m_private->m_text.lastAtom()->type() != Atom::ListItemLeft)
-            && (m_private->m_text.lastAtom()->type() != Atom::DivLeft)) {
+            && (m_private->m_text.lastAtom()->type() != Atom::DivLeft)
+            && (m_private->m_text.lastAtom()->type() != Atom::DetailsLeft)) {
             leaveValueList();
         }
 
@@ -2425,6 +2440,8 @@ int DocParser::endCmdFor(int cmd)
         return CMD_ENDCODE;
     case CMD_CODE:
         return CMD_ENDCODE;
+    case CMD_DETAILS:
+        return CMD_ENDDETAILS;
     case CMD_DIV:
         return CMD_ENDDIV;
     case CMD_QML:
diff --git a/src/qdoc/qdoc/htmlgenerator.cpp b/src/qdoc/qdoc/htmlgenerator.cpp
index 74ce2be7e..304989f9c 100644
--- a/src/qdoc/qdoc/htmlgenerator.cpp
+++ b/src/qdoc/qdoc/htmlgenerator.cpp
@@ -370,6 +370,16 @@ qsizetype HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, Co
                                  m_codePrefix, m_codeSuffix)
               << "</pre>\n";
         break;
+    case Atom::DetailsLeft:
+        out() << "<details>\n";
+        if (!atom->string().isEmpty())
+            out() << "<summary>" << protectEnc(atom->string()) << "</summary>\n";
+        else
+            out() << "<summary>...</summary>\n";
+        break;
+    case Atom::DetailsRight:
+        out() << "</details>\n";
+        break;
     case Atom::DivLeft:
         out() << "<div";
         if (!atom->string().isEmpty())
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput.xml
index 5f7308779..72905681d 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput.xml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput.xml
@@ -73,5 +73,8 @@
 <db:section xml:id="linking-to-something-in-a-section-title">
 <db:title>Linking to <db:link xlink:href="qdoctests-qdocfileoutput.xml#further-information">something</db:link> in a section title</db:title>
 <db:para>This is allowed but a questionable practice.</db:para>
+<db:note>
+<db:para>You're looking at detailed information.</db:para>
+</db:note>
 </db:section>
 </db:article>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput.webxml b/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput.webxml
index 3eb5b7703..13b3e5c51 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput.webxml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput.webxml
@@ -86,6 +86,8 @@
                 <section id="linking-to-something-in-a-section-title">
                     <heading level="1">Linking to <link raw="Further information" href="qdoctests-qdocfileoutput.html#further-information" type="page" page="Testing QDoc output from .qdoc files">something</link> in a section title</heading>
                     <para>This is allowed but a questionable practice.</para>
+                    <para>
+                        <bold>Note:</bold> You're looking at detailed information.</para>
                 </section>
             </description>
         </page>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput.html b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput.html
index 61b0e8bc1..74570305c 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput.html
@@ -55,6 +55,12 @@
 <p>This section title is overridden by another target which takes precedence.</p>
 <h2 id="linking-to-something-in-a-section-title">Linking to <a href="qdoctests-qdocfileoutput.html#further-information" translate="no">something</a> in a section title</h2>
 <p>This is allowed but a questionable practice.</p>
+<details>
+<summary>QDoc details</summary>
+<div class="admonition note">
+<p><b>Note: </b>You're looking at detailed information.</p>
+</div>
+</details>
 </div>
 <!-- @@@qdoctests-qdocfileoutput.html -->
 <p class="naviNextPrevious footerNavi">
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/tocbreadcrumbs/qdoctests-qdocfileoutput.html b/tests/auto/qdoc/generatedoutput/expected_output/tocbreadcrumbs/qdoctests-qdocfileoutput.html
index f9fa82782..cbb55db2e 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/tocbreadcrumbs/qdoctests-qdocfileoutput.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/tocbreadcrumbs/qdoctests-qdocfileoutput.html
@@ -57,6 +57,12 @@
 <p>This section title is overridden by another target which takes precedence.</p>
 <h2 id="linking-to-something-in-a-section-title">Linking to <a href="qdoctests-qdocfileoutput.html#further-information" translate="no">something</a> in a section title</h2>
 <p>This is allowed but a questionable practice.</p>
+<details>
+<summary>QDoc details</summary>
+<div class="admonition note">
+<p><b>Note: </b>You're looking at detailed information.</p>
+</div>
+</details>
 </div>
 <!-- @@@qdoctests-qdocfileoutput.html -->
 <p class="naviNextPrevious footerNavi">
diff --git a/tests/auto/qdoc/generatedoutput/testdata/outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc b/tests/auto/qdoc/generatedoutput/testdata/outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc
index 53fe34666..3deb39807 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc
+++ b/tests/auto/qdoc/generatedoutput/testdata/outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc
@@ -55,6 +55,10 @@
     \section1 Linking to \l {Further information}{something} in a section title
 
     This is allowed but a questionable practice.
+
+    \details {\PROD details}
+        \note You're looking at detailed information.
+    \enddetails
 */
 
 /*!
-- 
cgit v1.2.1