qdoc: Changed the <apiDesc> in the <cxxClass>.

This <apiDesc> is now the first part of the generated
documentation for a C++ class rather than the first
section of the detailed description. This includes
the brief text, the inheritance stuff, the inherited-by
stuff, and a few other preamble type texts.

2 files changed, 97 insertions, 49 deletions

diff --git a/tools/qdoc3/ditaxmlgenerator.cpp b/tools/qdoc3/ditaxmlgenerator.cpp
index 13d33e8..3efd98b 100644
--- a/tools/qdoc3/ditaxmlgenerator.cpp
+++ b/tools/qdoc3/ditaxmlgenerator.cpp
@@ -1443,7 +1443,6 @@ int DitaXmlGenerator::generateAtom(const Atom *atom,
 void
 DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* marker)
 {
-    QList<Section> sections;
     QList<Section>::ConstIterator s;
 
     const ClassNode* cn = 0;
@@ -1487,7 +1486,50 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark
         writeLocation(cn);
         xmlWriter().writeEndElement(); // <cxxClassDefinition>
 
-        writeDetailSections(cn, marker, true, QString("Detailed Description"));
+        xmlWriter().writeStartElement(APIDESC);
+        xmlWriter().writeAttribute("spectitle",title);
+        Text brief = cn->doc().briefText();
+        if (!brief.isEmpty()) {
+            xmlWriter().writeStartElement("p");
+            generateText(brief, cn, marker);
+            xmlWriter().writeEndElement(); // </p>
+        }
+        generateIncludes(cn, marker);
+        generateStatus(cn, marker);
+        generateInherits(cn, marker);
+        generateInheritedBy(cn, marker);
+        generateThreadSafeness(cn, marker);
+        generateSince(cn, marker);
+        
+        xmlWriter().writeStartElement("ul");
+        
+        QString membersLink = generateListOfAllMemberFile(inner, marker);
+        if (!membersLink.isEmpty()) {
+            writeXrefListItem(membersLink,"List of all members, including inherited members");
+        }
+        
+        QString obsoleteLink = generateLowStatusMemberFile(inner,
+                                                           marker,
+                                                           CodeMarker::Obsolete);
+        if (!obsoleteLink.isEmpty()) {
+            writeXrefListItem(obsoleteLink,"Obsolete members");
+        }
+
+        QString compatLink = generateLowStatusMemberFile(inner,
+                                                         marker,
+                                                         CodeMarker::Compat);
+        if (!compatLink.isEmpty()) {
+            writeXrefListItem(compatLink,"Qt 3 support members");
+        }
+
+        xmlWriter().writeEndElement(); // </ul>
+        xmlWriter().writeEndElement(); // </apiDesc>
+
+        QList<Section> summarySections;
+        summarySections = marker->sections(inner, CodeMarker::Summary, CodeMarker::Okay);
+
+        writeDetailedDescription(cn, marker, false, QString("Detailed Description"));
+
         // zzz writeSections() gores here.
         // not included: <example> or <apiImpl>
 
@@ -1496,9 +1538,10 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark
         // not included: <related-links>
         // not included: <cxxClassNested>
 
-        sections = marker->sections(inner, CodeMarker::Detailed, CodeMarker::Okay);
-        s = sections.begin();
-        while (s != sections.end()) {
+        QList<Section> detailSections;
+        detailSections = marker->sections(inner, CodeMarker::Detailed, CodeMarker::Okay);
+        s = detailSections.begin();
+        while (s != detailSections.end()) {
             if ((*s).name == "Member Function Documentation") {
                 writeFunctions((*s),cn,marker);
             }
@@ -1631,7 +1674,7 @@ void DitaXmlGenerator::generateFakeNode(const FakeNode *fake, CodeMarker *marker
             ++s;
         }
         
-        writeDetailSections(fake, marker, false, QString("Detailed Description"));
+        writeDetailedDescription(fake, marker, false, QString("Detailed Description"));
 
         if (cn)
             generateQmlText(cn->doc().body(), cn, marker, fake->name());
@@ -1660,10 +1703,10 @@ void DitaXmlGenerator::generateFakeNode(const FakeNode *fake, CodeMarker *marker
     if (!fake->doc().isEmpty()) {
         xmlWriter().writeStartElement("body");
         if (fake->subType() == Node::Module) {
-            writeDetailSections(fake, marker, false, QString("Detailed Description"));
+            writeDetailedDescription(fake, marker, false, QString("Detailed Description"));
         }
         else
-            writeDetailSections(fake, marker, false, QString());
+            writeDetailedDescription(fake, marker, false, QString());
         generateAlsoList(fake, marker);
 
         if (!fake->groupMembers().isEmpty()) {
@@ -1832,10 +1875,15 @@ void DitaXmlGenerator::generateBreadCrumbs(const QString& title,
 }
 
 /*!
-  Outputs an XML file header depending on which kind of DITA XML
-  file is being generated.
+  Writes an XML file header to the current XML stream. This
+  depends on which kind of DITA XML file is being generated,
+  which is determined by the \a node type and subtype and the
+  \a subpage flag. If the \subpage flag is true, a \c{<topic>}
+  header is written, regardless of the type of \a node.
  */
-void DitaXmlGenerator::generateHeader(const Node* node, const QString& name)
+void DitaXmlGenerator::generateHeader(const Node* node,
+                                      const QString& name,
+                                      bool subpage)
 {
     if (!node)
         return;
@@ -1848,16 +1896,7 @@ void DitaXmlGenerator::generateHeader(const Node* node, const QString& name)
     QString version;
     QString outputclass;
 
-    if (node->type() == Node::Class) {
-        mainElement = "cxxClass";
-        nameElement = "apiName";
-        dtd = "dtd/cxxClass.dtd";
-        version = "0.6.0";
-        doctype = "<!DOCTYPE " + mainElement +
-            " PUBLIC \"-//NOKIA//DTD DITA C++ API Class Reference Type v" +
-            version + "//EN\" \"" + dtd + "\">";
-    }
-    else if (node->type() == Node::Fake) {
+    if (node->type() == Node::Fake || subpage) {
         mainElement = "topic";
         nameElement = "title";
         dtd = "dtd/topic.dtd";
@@ -1895,6 +1934,15 @@ void DitaXmlGenerator::generateHeader(const Node* node, const QString& name)
             outputclass = "page";
         }
     }
+    else if (node->type() == Node::Class) {
+        mainElement = "cxxClass";
+        nameElement = "apiName";
+        dtd = "dtd/cxxClass.dtd";
+        version = "0.6.0";
+        doctype = "<!DOCTYPE " + mainElement +
+            " PUBLIC \"-//NOKIA//DTD DITA C++ API Class Reference Type v" +
+            version + "//EN\" \"" + dtd + "\">";
+    }
 
     xmlWriter().writeDTD(doctype);
     xmlWriter().writeComment(node->doc().location().fileName());
@@ -1949,7 +1997,7 @@ void DitaXmlGenerator::generateBrief(const Node* node, CodeMarker* marker)
         ++noLinks;
         xmlWriter().writeStartElement(SHORTDESC);
         generateText(brief, node, marker);
-        xmlWriter().writeEndElement(); // shortdesc
+        xmlWriter().writeEndElement(); // </shortdesc>
         --noLinks;
     }
 }
@@ -2186,7 +2234,7 @@ QString DitaXmlGenerator::generateListOfAllMemberFile(const InnerNode* inner,
     QString fileName = fileBase(inner) + "-members." + fileExtension(inner);
     beginSubPage(inner->location(), fileName);
     QString title = "List of All Members for " + inner->name();
-    generateHeader(inner, title);
+    generateHeader(inner, title, true);
     xmlWriter().writeStartElement("body");
     xmlWriter().writeStartElement("section");
     if (!title.isEmpty()) {
@@ -2235,7 +2283,7 @@ QString DitaXmlGenerator::generateLowStatusMemberFile(const InnerNode* inner,
         fileName = fileBase(inner) + "-obsolete." + fileExtension(inner);
     }
     beginSubPage(inner->location(), fileName);
-    generateHeader(inner, title);
+    generateHeader(inner, title, true);
     xmlWriter().writeStartElement("body");
     xmlWriter().writeStartElement("section");
     if (!title.isEmpty()) {
@@ -4531,7 +4579,7 @@ void DitaXmlGenerator::writeFunctions(const Section& s,
             writeLocation(fn);
             xmlWriter().writeEndElement(); // <cxxFunctionDefinition>
 
-            writeDetailSections(fn, marker, true, QString());
+            writeDetailedDescription(fn, marker, true, QString());
             // generateAlsoList(inner, marker);
 
             // not included: <example> or <apiImpl>
@@ -4687,7 +4735,7 @@ void DitaXmlGenerator::writeEnumerations(const Section& s,
             writeLocation(en);
             xmlWriter().writeEndElement(); // <cxxEnumerationDefinition>
 
-            writeDetailSections(en, marker, true, QString());
+            writeDetailedDescription(en, marker, true, QString());
 
             // not included: <example> or <apiImpl>
 
@@ -4747,7 +4795,7 @@ void DitaXmlGenerator::writeTypedefs(const Section& s,
             writeLocation(tn);
             xmlWriter().writeEndElement(); // <cxxTypedefDefinition>
 
-            writeDetailSections(tn, marker, true, QString());
+            writeDetailedDescription(tn, marker, true, QString());
 
             // not included: <example> or <apiImpl>
 
@@ -4858,7 +4906,7 @@ void DitaXmlGenerator::writeProperties(const Section& s,
             writeLocation(pn);
             xmlWriter().writeEndElement(); // <cxxVariableDefinition>
 
-            writeDetailSections(pn, marker, true, QString());
+            writeDetailedDescription(pn, marker, true, QString());
             
             // not included: <example> or <apiImpl>
 
@@ -4940,7 +4988,7 @@ void DitaXmlGenerator::writeDataMembers(const Section& s,
             writeLocation(vn);
             xmlWriter().writeEndElement(); // <cxxVariableDefinition>
 
-            writeDetailSections(vn, marker, true, QString());
+            writeDetailedDescription(vn, marker, true, QString());
 
             // not included: <example> or <apiImpl>
 
@@ -5034,7 +5082,7 @@ void DitaXmlGenerator::writeMacros(const Section& s,
                 writeLocation(fn);
                 xmlWriter().writeEndElement(); // <cxxDefineDefinition>
 
-                writeDetailSections(fn, marker, true, QString());
+                writeDetailedDescription(fn, marker, true, QString());
 
                 // not included: <example> or <apiImpl>
 
@@ -5110,21 +5158,19 @@ QXmlStreamWriter& DitaXmlGenerator::xmlWriter()
 }
 
 /*!
-  Writes the \e {Detailed Description} section(s) for \a node
-  to the current XML stream using the code \a marker. if the
-  \a apiDesc flag is true, then the first section of the
-  sequence of sections written will be an \c {apiDesc>}
-  element with a \e {spectitle} attribute of \e {Detailed
-  Description}. Otherwise, the first section will be a
-  \c {<section>} element with a \c {<title>} element of
-  \e {Detailed Description}. This function calls the
-  Generator::generateBody() function to write the XML for
-  the section list.
+  Writes the \e {Detailed Description} section(s) for \a node to the
+  current XML stream using the code \a marker. if the \a apiDesc flag
+  is true, then the first section of the sequence of sections written
+  will be an \c {apiDesc>} element with a \e {spectitle} attribute of
+  \e {Detailed Description}. Otherwise, the first section will be a
+  \c {<section>} element with a \c {<title>} element of \e {Detailed
+  Description}. This function calls the Generator::generateBody()
+  function to write the XML for the section list.
  */
-void DitaXmlGenerator::writeDetailSections(const Node* node,
-                                           CodeMarker* marker,
-                                           bool apiDesc,
-                                           const QString& title)
+void DitaXmlGenerator::writeDetailedDescription(const Node* node,
+                                                CodeMarker* marker,
+                                                bool apiDesc,
+                                                const QString& title)
 {
     if (!node->doc().isEmpty()) {
         inDetailedDescription = true;
diff --git a/tools/qdoc3/ditaxmlgenerator.h b/tools/qdoc3/ditaxmlgenerator.h
index 6a52441..5ec4a6c 100644
--- a/tools/qdoc3/ditaxmlgenerator.h
+++ b/tools/qdoc3/ditaxmlgenerator.h
@@ -150,7 +150,9 @@ class DitaXmlGenerator : public PageGenerator
     void generateBreadCrumbs(const QString& title,
                              const Node* node,
                              CodeMarker* marker);
-    void generateHeader(const Node* node, const QString& name);
+    void generateHeader(const Node* node, 
+                        const QString& name,
+                        bool subpage = false);
     void generateTitle(const QString& title, 
                        const Text& subTitle, 
                        SubTitleSize subTitleSize,
@@ -261,10 +263,10 @@ class DitaXmlGenerator : public PageGenerator
     virtual void beginSubPage(const Location& location, const QString& fileName);
     virtual void endSubPage();
     QXmlStreamWriter& xmlWriter();
-    void writeDetailSections(const Node* node,
-                             CodeMarker* marker,
-                             bool apiDesc,
-                             const QString& title);
+    void writeDetailedDescription(const Node* node,
+                                  CodeMarker* marker,
+                                  bool apiDesc,
+                                  const QString& title);
     void addLink(const QString& href, const QStringRef& text);
 
  private: