qdoc: Briefs from other modules now show up

The brief text for a documented thing is now output as an
attribute of that thing in the module's index file, and it
is reconstituted in the thing's tree node, when qdoc reads
the module's index file later. Only the verbatim text of
the brief is saved in the index file, i.e. no links or
other markup.

The effect is that brief texts can be used in other modules.

Task-number: QTBUG-31021
Change-Id: I932a0c85259b6d1901138f0c0959ddb9815b7db5
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

src/tools/qdoc/ditaxmlgenerator.cpp

@@ -2763,11 +2763,22 @@ void DitaXmlGenerator::generateAnnotatedList(const Node* relative,
                 writeEndTag(); // </p>
                 writeEndTag(); // <entry>
             }
+            else if (!node->reconstitutedBrief().isEmpty()) {
+                writeStartTag(DT_entry);
+                writeStartTag(DT_p);
+                writeCharacters(node->reconstitutedBrief());
+                writeEndTag(); // </p>
+                writeEndTag(); // <entry>
+            }
         }
         else {
             writeStartTag(DT_entry);
             writeStartTag(DT_p);
-            writeCharacters(protectEnc(node->doc().briefText().toString())); // zzz
+            if (!node->reconstitutedBrief().isEmpty()) {
+                writeCharacters(node->reconstitutedBrief());
+            }
+            else
+                writeCharacters(protectEnc(node->doc().briefText().toString()));
             writeEndTag(); // </p>
             writeEndTag(); // <entry>
         }

src/tools/qdoc/htmlgenerator.cpp

@@ -2287,10 +2287,19 @@ void HtmlGenerator::generateAnnotatedList(const Node *relative,
                 generateText(brief, node, marker);
                 out() << "</p></td>";
             }
+            else if (!node->reconstitutedBrief().isEmpty()) {
+                out() << "<td class=\"tblDescr\"><p>";
+                out() << node->reconstitutedBrief();
+                out() << "</p></td>";
+            }
         }
         else {
             out() << "<td class=\"tblDescr\"><p>";
-            out() << protectEnc(node->doc().briefText().toString());
+            if (!node->reconstitutedBrief().isEmpty()) {
+                out() << node->reconstitutedBrief();
+            }
+            else
+                out() << protectEnc(node->doc().briefText().toString());
             out() << "</p></td>";
         }
         out() << "</tr>\n";

src/tools/qdoc/node.h

@@ -179,6 +179,7 @@ public:
     void setLink(LinkType linkType, const QString &link, const QString &desc);
     void setUrl(const QString &url);
     void setTemplateStuff(const QString &templateStuff) { templateStuff_ = templateStuff; }
+    void setReconstitutedBrief(const QString &t) { reconstitutedBrief_ = t; }
     void setPageType(PageType t) { pageType_ = t; }
     void setPageType(const QString& t);
     void setParent(InnerNode* n) { parent_ = n; }
@@ -237,6 +238,7 @@ public:
     ThreadSafeness inheritedThreadSafeness() const;
     QString since() const { return since_; }
     QString templateStuff() const { return templateStuff_; }
+    const QString& reconstitutedBrief() const { return reconstitutedBrief_; }
     PageType pageType() const { return pageType_; }
     QString pageTypeString() const;
     QString nodeTypeString() const;
@@ -298,6 +300,7 @@ private:
     QString url_;
     QString since_;
     QString templateStuff_;
+    QString reconstitutedBrief_;
     mutable QString uuid_;
     QString outSubDir_;
     QString qmlModuleName_;

src/tools/qdoc/qdocindexfiles.cpp

@@ -505,6 +505,10 @@ void QDocIndexFiles::readIndexSection(const QDomElement& element,
     node->setDoc(doc);
     node->setIndexNodeFlag();
     node->setOutputSubdirectory(project_.toLower());
+    QString briefAttr = element.attribute("brief");
+    if (!briefAttr.isEmpty()) {
+        node->setReconstitutedBrief(briefAttr);
+    }
 
     if (node->isInnerNode()) {
         InnerNode* inner = static_cast<InnerNode*>(node);
@@ -960,6 +964,9 @@ bool QDocIndexFiles::generateIndexSection(QXmlStreamWriter& writer,
     default:
         break;
     }
+    QString brief = node->doc().briefText().toString();
+    if (!brief.isEmpty())
+        writer.writeAttribute("brief", brief);
 
     // Inner nodes and function nodes contain child nodes of some sort, either
     // actual child nodes or function parameters. For these, we close the

src/tools/qdoc/text.cpp

@@ -149,6 +149,11 @@ void Text::stripLastAtom()
     }
 }
 
+/*!
+  This function traverses the atom list of the Text object,
+  extracting all the string parts. It concatenates them to
+  a result string and returns it.
+ */
 QString Text::toString() const
 {
     QString str;