From 843b7f1a1705e2f1b207eb4958be87d570ac7a5f Mon Sep 17 00:00:00 2001
From: Martin Smith <martin.smith@digia.com>
Date: Tue, 7 May 2013 14:40:36 +0200
Subject: [PATCH] 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 | 13 ++++++++++++-
 src/tools/qdoc/htmlgenerator.cpp    | 11 ++++++++++-
 src/tools/qdoc/node.h               |  3 +++
 src/tools/qdoc/qdocindexfiles.cpp   |  7 +++++++
 src/tools/qdoc/text.cpp             |  5 +++++
 5 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/src/tools/qdoc/ditaxmlgenerator.cpp b/src/tools/qdoc/ditaxmlgenerator.cpp
index 314dda3a9d..eea1845e17 100644
--- a/src/tools/qdoc/ditaxmlgenerator.cpp
+++ b/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>
         }
diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp
index f74a1d2fa0..2dc4c1e6c6 100644
--- a/src/tools/qdoc/htmlgenerator.cpp
+++ b/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";
diff --git a/src/tools/qdoc/node.h b/src/tools/qdoc/node.h
index 326146a962..bc75df2992 100644
--- a/src/tools/qdoc/node.h
+++ b/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_;
diff --git a/src/tools/qdoc/qdocindexfiles.cpp b/src/tools/qdoc/qdocindexfiles.cpp
index 59adc63c9e..d984681a08 100644
--- a/src/tools/qdoc/qdocindexfiles.cpp
+++ b/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
diff --git a/src/tools/qdoc/text.cpp b/src/tools/qdoc/text.cpp
index 2d218bd469..e2f682726d 100644
--- a/src/tools/qdoc/text.cpp
+++ b/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;