qdoc: Allowed multiple values for certain metadata tags.

Also output mainters for classes in the HTML output,
if there are maintainers listed.

9 files changed, 152 insertions, 44 deletions

diff --git a/tools/qdoc3/config.cpp b/tools/qdoc3/config.cpp
index 267a09c..838f6ac 100644
--- a/tools/qdoc3/config.cpp
+++ b/tools/qdoc3/config.cpp
@@ -338,7 +338,7 @@ QSet<QString> Config::subVars(const QString& var) const
 {
     QSet<QString> result;
     QString varDot = var + QLatin1Char('.');
-    QMap<QString, QString>::ConstIterator v = stringValueMap.begin();
+    QStringMultiMap::ConstIterator v = stringValueMap.begin();
     while (v != stringValueMap.end()) {
         if (v.key().startsWith(varDot)) {
             QString subVar = v.key().mid(varDot.length());
@@ -357,10 +357,10 @@ QSet<QString> Config::subVars(const QString& var) const
   with the matching keys (stripped of the prefix \a var and
   mapped to their values. The pairs are inserted into \a t
  */
-void Config::subVarsAndValues(const QString& var, QStringMap& t) const
+void Config::subVarsAndValues(const QString& var, QStringMultiMap& t) const
 {
     QString varDot = var + QLatin1Char('.');
-    QMap<QString, QString>::ConstIterator v = stringValueMap.begin();
+    QStringMultiMap::ConstIterator v = stringValueMap.begin();
     while (v != stringValueMap.end()) {
         if (v.key().startsWith(varDot)) {
             QString subVar = v.key().mid(varDot.length());
diff --git a/tools/qdoc3/config.h b/tools/qdoc3/config.h
index 767acb1..8e19ed2 100644
--- a/tools/qdoc3/config.h
+++ b/tools/qdoc3/config.h
@@ -54,7 +54,7 @@
 
 QT_BEGIN_NAMESPACE
 
-typedef QMap<QString,QString> QStringMap;
+typedef QMultiMap<QString, QString> QStringMultiMap;
 
 class Config
 {
@@ -76,7 +76,7 @@ class Config
     QRegExp getRegExp(const QString& var) const;
     QList<QRegExp> getRegExpList(const QString& var) const;
     QSet<QString> subVars(const QString& var) const;
-    void subVarsAndValues(const QString& var, QStringMap& t) const;
+    void subVarsAndValues(const QString& var, QStringMultiMap& t) const;
     QStringList getAllFiles(const QString& filesVar, 
                             const QString& dirsVar,
                             const QSet<QString> &excludedDirs = QSet<QString>());
diff --git a/tools/qdoc3/ditaxmlgenerator.cpp b/tools/qdoc3/ditaxmlgenerator.cpp
index 4b4f776..1bc4992 100644
--- a/tools/qdoc3/ditaxmlgenerator.cpp
+++ b/tools/qdoc3/ditaxmlgenerator.cpp
@@ -5566,24 +5566,12 @@ void DitaXmlGenerator::writeDitaMap()
   \note If \a t is found in the metadata map, it is erased.
   i.e. Once you call this function for a particular \a t,
   you consume \a t.
-
-  At the moment, it doesn't chaeck to see if there is a
-  default value for the tag. But it will eventually.
  */
 bool DitaXmlGenerator::writeMetadataElement(const InnerNode* inner,
                                             DitaXmlGenerator::DitaTag t,
                                             bool force)
 {
-    QString s;
-    QStringMap& metaTagMap = const_cast<QStringMap&>(inner->doc().metaTagMap());
-    QStringMap::iterator i = metaTagMap.find(ditaTags[t]);
-    if (i == metaTagMap.end()) {
-        s = metadataDefault(t);
-    }
-    else {
-        s = i.value();
-        metaTagMap.erase(i);
-    }
+    QString s = getMetadataElement(inner,t);
     if (s.isEmpty() && !force)
         return false;
     writeStartTag(t);
@@ -5593,6 +5581,34 @@ bool DitaXmlGenerator::writeMetadataElement(const InnerNode* inner,
     return true;
 }
 
+
+/*!
+  Looks up the tag name for \a t in the map of metadata
+  values for the current topic in \a inner. If one or more
+  value sfor the tag are found, the elements are written.
+  Otherwise nothing is written.
+
+  Returns true or false depending on whether it writes
+  at least one element using the tag \a t.
+
+  \note If \a t is found in the metadata map, it is erased.
+  i.e. Once you call this function for a particular \a t,
+  you consume \a t.
+ */
+bool DitaXmlGenerator::writeMetadataElements(const InnerNode* inner,
+                                             DitaXmlGenerator::DitaTag t)
+{
+    QStringList s = getMetadataElements(inner,t);
+    if (s.isEmpty())
+        return false;
+    for (int i=0; i<s.size(); ++i) {
+        writeStartTag(t);
+        xmlWriter().writeCharacters(s[i]);
+        writeEndTag();
+    }
+    return true;
+}
+
 /*!
   Looks up the tag name for \a t in the map of metadata
   values for the current topic in \a inner. If a value
@@ -5604,16 +5620,29 @@ bool DitaXmlGenerator::writeMetadataElement(const InnerNode* inner,
  */
 QString DitaXmlGenerator::getMetadataElement(const InnerNode* inner, DitaXmlGenerator::DitaTag t)
 {
-    QString s;
-    QStringMap& metaTagMap = const_cast<QStringMap&>(inner->doc().metaTagMap());
-    QStringMap::iterator i = metaTagMap.find(ditaTags[t]);
-    if (i != metaTagMap.end()) {
-        s = i.value();
-        metaTagMap.erase(i);
-    }
-    else {
+    QString s = Generator::getMetadataElement(inner, ditaTags[t]);
+    if (s.isEmpty())
         s = metadataDefault(t);
-    }
+    return s;
+}
+
+/*!
+  Looks up the tag name for \a t in the map of metadata
+  values for the current topic in \a inner. If values
+  for the tag are found, they are returned in a string
+  list.
+
+  \note If \a t is found in the metadata map, all the
+  pairs having the key \a t are erased. i.e. Once you
+  all this function for a particular \a t, you consume
+  \a t.
+ */
+QStringList DitaXmlGenerator::getMetadataElements(const InnerNode* inner,
+                                                  DitaXmlGenerator::DitaTag t)
+{
+    QStringList s = Generator::getMetadataElements(inner,ditaTags[t]);
+    if (s.isEmpty())
+        s.append(metadataDefault(t));
     return s;
 }
 
@@ -5671,7 +5700,7 @@ DitaXmlGenerator::writeProlog(const InnerNode* inner, CodeMarker* marker)
     if (!inner)
         return;
     writeStartTag(DT_prolog);
-    writeMetadataElement(inner,DT_author);
+    writeMetadataElements(inner,DT_author);
     writeMetadataElement(inner,DT_publisher);
     QString s = getMetadataElement(inner,DT_copyryear);
     QString t = getMetadataElement(inner,DT_copyrholder);
@@ -5690,11 +5719,13 @@ DitaXmlGenerator::writeProlog(const InnerNode* inner, CodeMarker* marker)
     xmlWriter().writeAttribute("view",s);
     writeEndTag(); // </permissions>
     writeStartTag(DT_metadata);
-    s = getMetadataElement(inner,DT_audience);
-    if (!s.isEmpty()) {
-        writeStartTag(DT_audience);
-        xmlWriter().writeAttribute("type",s);
-        writeEndTag(); // </audience>
+    QStringList sl = getMetadataElements(inner,DT_audience);
+    if (!sl.isEmpty()) {
+        for (int i=0; i<sl.size(); ++i) {
+            writeStartTag(DT_audience);
+            xmlWriter().writeAttribute("type",sl[i]);
+            writeEndTag(); // </audience>
+        }
     }
     if (!writeMetadataElement(inner,DT_category,false)) {
         writeStartTag(DT_category);
@@ -5755,7 +5786,7 @@ DitaXmlGenerator::writeProlog(const InnerNode* inner, CodeMarker* marker)
         }
         writeEndTag(); // </prodinfo>
     }
-    const QStringMap& metaTagMap = inner->doc().metaTagMap(); 
+    const QStringMultiMap& metaTagMap = inner->doc().metaTagMap(); 
     QMapIterator<QString, QString> i(metaTagMap);
     while (i.hasNext()) {
         i.next();
diff --git a/tools/qdoc3/ditaxmlgenerator.h b/tools/qdoc3/ditaxmlgenerator.h
index c7400bb..ffca234 100644
--- a/tools/qdoc3/ditaxmlgenerator.h
+++ b/tools/qdoc3/ditaxmlgenerator.h
@@ -319,7 +319,9 @@ class DitaXmlGenerator : public PageGenerator
     bool writeMetadataElement(const InnerNode* inner, 
                               DitaXmlGenerator::DitaTag t, 
                               bool force=true);
+    bool writeMetadataElements(const InnerNode* inner, DitaXmlGenerator::DitaTag t);
     QString getMetadataElement(const InnerNode* inner, DitaXmlGenerator::DitaTag t);
+    QStringList getMetadataElements(const InnerNode* inner, DitaXmlGenerator::DitaTag t);
 
  private:
     enum SubTitleSize { SmallSubTitle, LargeSubTitle };
@@ -516,7 +518,7 @@ class DitaXmlGenerator : public PageGenerator
     static QString ditaTags[];
     QStack<QXmlStreamWriter*> xmlWriterStack;
     QStack<DitaTag> tagStack;
-    QStringMap metadataDefaults;
+    QStringMultiMap metadataDefaults;
 };
 
 #define DITAXMLGENERATOR_ADDRESS           "address"
diff --git a/tools/qdoc3/doc.cpp b/tools/qdoc3/doc.cpp
index 66acacf..2239f43 100644
--- a/tools/qdoc3/doc.cpp
+++ b/tools/qdoc3/doc.cpp
@@ -63,6 +63,7 @@ Q_GLOBAL_STATIC(QSet<QString>, null_Set_QString)
 Q_GLOBAL_STATIC(QStringList, null_QStringList)
 Q_GLOBAL_STATIC(QList<Text>, null_QList_Text)
 Q_GLOBAL_STATIC(QStringMap, null_QStringMap)
+Q_GLOBAL_STATIC(QStringMultiMap, null_QStringMultiMap)
 
 struct Macro
 {
@@ -228,7 +229,7 @@ class DocPrivateExtra
     QList<int>          tableOfContentsLevels;
     QList<Atom*>        keywords;
     QList<Atom*>        targets;
-    QStringMap          metaMap;
+    QStringMultiMap          metaMap;
 
     DocPrivateExtra()
         : granularity(Doc::Part) { }
@@ -2960,9 +2961,9 @@ const QList<Atom *> &Doc::targets() const
     return priv->extra->targets;
 }
 
-const QStringMap &Doc::metaTagMap() const
+const QStringMultiMap &Doc::metaTagMap() const
 {
-    return priv && priv->extra ? priv->extra->metaMap : *null_QStringMap();
+    return priv && priv->extra ? priv->extra->metaMap : *null_QStringMultiMap();
 }
 
 void Doc::initialize(const Config& config)
diff --git a/tools/qdoc3/doc.h b/tools/qdoc3/doc.h
index ea832b1..e043b3a 100644
--- a/tools/qdoc3/doc.h
+++ b/tools/qdoc3/doc.h
@@ -64,7 +64,6 @@ class FakeNode;
 
 typedef QMap<QString, QStringList> QCommandMap;
 typedef QMap<QString, QString> QStringMap;
-typedef QStringMap::const_iterator QStringMapEntry; 
 typedef QMultiMap<QString, QString> QStringMultiMap;
 
 class Doc
@@ -118,7 +117,7 @@ class Doc
     const QList<int> &tableOfContentsLevels() const;
     const QList<Atom *> &keywords() const;
     const QList<Atom *> &targets() const;
-    const QStringMap &metaTagMap() const;
+    const QStringMultiMap &metaTagMap() const;
 
     static void initialize( const Config &config );
     static void terminate();
diff --git a/tools/qdoc3/generator.cpp b/tools/qdoc3/generator.cpp
index b4768db..f05c030 100644
--- a/tools/qdoc3/generator.cpp
+++ b/tools/qdoc3/generator.cpp
@@ -549,7 +549,10 @@ void Generator::generateAlsoList(const Node *node, CodeMarker *marker)
 
     if (!alsoList.isEmpty()) {
         Text text;
-        text << Atom::ParaLeft << "See also ";
+        text << Atom::ParaLeft
+             << Atom(Atom::FormattingLeft,ATOM_FORMATTING_BOLD)
+             << "See also "
+             << Atom(Atom::FormattingRight,ATOM_FORMATTING_BOLD);
 
         for (int i = 0; i < alsoList.size(); ++i)
             text << alsoList.at(i) << separator(i, alsoList.size());
@@ -559,6 +562,28 @@ void Generator::generateAlsoList(const Node *node, CodeMarker *marker)
     }
 }
 
+/*!
+  Generate a list of maintainers in the output
+ */
+void Generator::generateMaintainerList(const InnerNode* node, CodeMarker* marker)
+{
+    QStringList sl = getMetadataElements(node,"maintainer");
+
+    if (!sl.isEmpty()) {
+        Text text;
+        text << Atom::ParaLeft
+             << Atom(Atom::FormattingLeft,ATOM_FORMATTING_BOLD)
+             << "Maintained by: "
+             << Atom(Atom::FormattingRight,ATOM_FORMATTING_BOLD);
+
+        for (int i = 0; i < sl.size(); ++i)
+            text << sl.at(i) << separator(i, sl.size());
+
+        text << Atom::ParaRight;
+        generateText(text, node, marker);
+    }
+}
+
 void Generator::generateInherits(const ClassNode *classe, CodeMarker *marker)
 {
     QList<RelatedClass>::ConstIterator r;
@@ -566,7 +591,10 @@ void Generator::generateInherits(const ClassNode *classe, CodeMarker *marker)
 
     if (!classe->baseClasses().isEmpty()) {
         Text text;
-        text << Atom::ParaLeft << "Inherits ";
+        text << Atom::ParaLeft
+             << Atom(Atom::FormattingLeft,ATOM_FORMATTING_BOLD)
+             << "Inherits: "
+             << Atom(Atom::FormattingRight,ATOM_FORMATTING_BOLD);
 
         r = classe->baseClasses().begin();
         index = 0;
@@ -604,7 +632,10 @@ void Generator::generateInheritedBy(const ClassNode *classe,
 {
     if (!classe->derivedClasses().isEmpty()) {
         Text text;
-        text << Atom::ParaLeft << "Inherited by ";
+        text << Atom::ParaLeft
+             << Atom(Atom::FormattingLeft,ATOM_FORMATTING_BOLD)
+             << "Inherited by: "
+             << Atom(Atom::FormattingRight,ATOM_FORMATTING_BOLD);
 
         appendSortedNames(text, classe, classe->derivedClasses(), marker);
         text << Atom::ParaRight;
@@ -1275,4 +1306,44 @@ QString Generator::outputPrefix(const QString &nodeType)
     return outputPrefixes[nodeType];
 }
 
+/*!
+  Looks up the tag \a t in the map of metadata values for the
+  current topic in \a inner. If a value for the tag is found,
+  the value is returned.
+
+  \note If \a t is found in the metadata map, it is erased.
+  i.e. Once you call this function for a particular \a t,
+  you consume \a t.
+ */
+QString Generator::getMetadataElement(const InnerNode* inner, const QString& t)
+{
+    QString s;
+    QStringMultiMap& metaTagMap = const_cast<QStringMultiMap&>(inner->doc().metaTagMap());
+    QStringMultiMap::iterator i = metaTagMap.find(t);
+    if (i != metaTagMap.end()) {
+        s = i.value();
+        metaTagMap.erase(i);
+    }
+    return s;
+}
+
+/*!
+  Looks up the tag \a t in the map of metadata values for the
+  current topic in \a inner. If values for the tag are found,
+  they are returned in a string list.
+
+  \note If \a t is found in the metadata map, all the pairs
+  having the key \a t are erased. i.e. Once you call this
+  function for a particular \a t, you consume \a t.
+ */
+QStringList Generator::getMetadataElements(const InnerNode* inner, const QString& t)
+{
+    QStringList s;
+    QStringMultiMap& metaTagMap = const_cast<QStringMultiMap&>(inner->doc().metaTagMap());
+    s = metaTagMap.values(t);
+    if (!s.isEmpty())
+        metaTagMap.remove(t);
+    return s;
+}
+
 QT_END_NAMESPACE
diff --git a/tools/qdoc3/generator.h b/tools/qdoc3/generator.h
index 4482313..8fd5370 100644
--- a/tools/qdoc3/generator.h
+++ b/tools/qdoc3/generator.h
@@ -106,6 +106,7 @@ class Generator
 #endif
     virtual void generateBody(const Node *node, CodeMarker *marker);
     virtual void generateAlsoList(const Node *node, CodeMarker *marker);
+    virtual void generateMaintainerList(const InnerNode* node, CodeMarker* marker);
     virtual void generateInherits(const ClassNode *classe,
                                   CodeMarker *marker);
     virtual void generateInheritedBy(const ClassNode *classe,
@@ -141,7 +142,6 @@ class Generator
     void unknownAtom(const Atom *atom);
     QMap<QString, QString> &formattingLeftMap();
     QMap<QString, QString> &formattingRightMap();
-
     QMap<QString, QStringList> editionModuleMap;
     QMap<QString, QStringList> editionGroupMap;
 
@@ -150,6 +150,9 @@ class Generator
     static void supplementAlsoList(const Node *node, QList<Text> &alsoList);
     static QString outputPrefix(const QString &nodeType);
 
+    QString getMetadataElement(const InnerNode* inner, const QString& t);
+    QStringList getMetadataElements(const InnerNode* inner, const QString& t);
+
  private:
     void generateReimplementedFrom(const FunctionNode *func,
                                    CodeMarker *marker);
diff --git a/tools/qdoc3/htmlgenerator.cpp b/tools/qdoc3/htmlgenerator.cpp
index d1d1561..645453b 100644
--- a/tools/qdoc3/htmlgenerator.cpp
+++ b/tools/qdoc3/htmlgenerator.cpp
@@ -1327,6 +1327,7 @@ void HtmlGenerator::generateClassLikeNode(const InnerNode *inner,
         generateBody(inner, marker);
         out() << "</div>\n"; // QTBUG-9504
         generateAlsoList(inner, marker);
+        generateMaintainerList(inner, marker);
         generateExtractionMark(inner, EndMark);
     }