From 21fbfdb2acdc368c047d14004373d2d0baa6c0b1 Mon Sep 17 00:00:00 2001
From: Leandro Melo <leandro.melo@nokia.com>
Date: Wed, 14 Jul 2010 16:33:49 +0200
Subject: Docs: HTML comments marks so Creator can extract data efficiently.

Reviewed-by: Martin Smith
---
 tools/qdoc3/htmlgenerator.cpp | 50 ++++++++++++++++++++++++++++++++++++++++++-
 tools/qdoc3/htmlgenerator.h   |  7 ++++++
 tools/qdoc3/node.cpp          | 18 ++++++++++++++++
 tools/qdoc3/node.h            |  1 +
 4 files changed, 75 insertions(+), 1 deletion(-)

diff --git a/tools/qdoc3/htmlgenerator.cpp b/tools/qdoc3/htmlgenerator.cpp
index 89b1e98..16c5eb2 100644
--- a/tools/qdoc3/htmlgenerator.cpp
+++ b/tools/qdoc3/htmlgenerator.cpp
@@ -1382,12 +1382,14 @@ void HtmlGenerator::generateClassLikeNode(const InnerNode *inner,
     out() << "<a name=\"" << registerRef("details") << "\"></a><div class=\"navTop\"><a href=\"#toc\"><img src=\"./images/bullet_up.png\"></a></div>\n";
 
     if (!inner->doc().isEmpty()) {
+        generateExtractionMark(inner, DetailedDescriptionMark);
         //out() << "<hr />\n"
         out() << "<div class=\"descr\"/>\n" // QTBUG-9504
               << "<h2>" << "Detailed Description" << "</h2>\n";
         generateBody(inner, marker);
         out() << "</div>\n"; // QTBUG-9504
         generateAlsoList(inner, marker);
+        generateExtractionMark(inner, EndMark);
     }
 
     sections = marker->sections(inner, CodeMarker::Detailed, CodeMarker::Okay);
@@ -1593,12 +1595,14 @@ void HtmlGenerator::generateFakeNode(const FakeNode *fake, CodeMarker *marker)
             ++s;
         }
 
+        generateExtractionMark(fake, DetailedDescriptionMark);
         out() << "<a name=\"" << registerRef("details") << "\"></a><div class=\"navTop\"><a href=\"#toc\"><img src=\"./images/bullet_up.png\"></a></div>\n";
         out() << "<h2>" << "Detailed Description" << "</h2>\n";
         generateBody(fake, marker);
         if (cn)
             generateQmlText(cn->doc().body(), cn, marker, fake->name());
         generateAlsoList(fake, marker);
+        generateExtractionMark(fake, EndMark);
         //out() << "<hr />\n";
 
         sections = marker->qmlSections(qml_cn,CodeMarker::Detailed);
@@ -1631,16 +1635,20 @@ void HtmlGenerator::generateFakeNode(const FakeNode *fake, CodeMarker *marker)
 
     Text brief = fake->doc().briefText();
     if (fake->subType() == Node::Module && !brief.isEmpty()) {
+        generateExtractionMark(fake, DetailedDescriptionMark);
         out() << "<a name=\"" << registerRef("details") << "\"></a><div class=\"navTop\"><a href=\"#toc\"><img src=\"./images/bullet_up.png\"></a></div>\n";
         out() << "<div class=\"descr\"/>\n"; // QTBUG-9504
         out() << "<h2>" << "Detailed Description" << "</h2>\n";
     }
-    else
+    else {
+        generateExtractionMark(fake, DetailedDescriptionMark);
         out() << "<div class=\"descr\"/>\n"; // QTBUG-9504
+    }
 
     generateBody(fake, marker);
     out() << "</div>\n"; // QTBUG-9504
     generateAlsoList(fake, marker);
+    generateExtractionMark(fake, EndMark);
 
     if (!fake->groupMembers().isEmpty()) {
         NodeMap groupMembersMap;
@@ -1913,6 +1921,7 @@ void HtmlGenerator::generateBrief(const Node *node, CodeMarker *marker,
 {
     Text brief = node->doc().briefText();
     if (!brief.isEmpty()) {
+        generateExtractionMark(node, BriefMark);
         out() << "<p>";
         generateText(brief, node, marker);
         if (!relative || node == relative)
@@ -1920,6 +1929,7 @@ void HtmlGenerator::generateBrief(const Node *node, CodeMarker *marker,
         else
             out() << " <a href=\"" << linkForNode(node, relative) << "#";
         out() << registerRef("details") << "\">More...</a></p>\n";
+        generateExtractionMark(node, EndMark);
     }
 }
 
@@ -3504,6 +3514,7 @@ void HtmlGenerator::generateDetailedMember(const Node *node,
 #ifdef GENERATE_MAC_REFS    
     generateMacRef(node, marker);
 #endif    
+    generateExtractionMark(node, MemberMark);
     if (node->type() == Node::Enum
             && (enume = static_cast<const EnumNode *>(node))->flagsType()) {
 #ifdef GENERATE_MAC_REFS    
@@ -3566,6 +3577,7 @@ void HtmlGenerator::generateDetailedMember(const Node *node,
         }
     }
     generateAlsoList(node, marker);
+    generateExtractionMark(node, EndMark);
 }
 
 void HtmlGenerator::findAllClasses(const InnerNode *node)
@@ -4148,6 +4160,7 @@ void HtmlGenerator::generateDetailedQmlMember(const Node *node,
 #ifdef GENERATE_MAC_REFS    
     generateMacRef(node, marker);
 #endif    
+    generateExtractionMark(node, MemberMark);
     out() << "<div class=\"qmlitem\">";
     if (node->subType() == Node::QmlPropertyGroup) {
         const QmlPropGroupNode* qpgn = static_cast<const QmlPropGroupNode*>(node);
@@ -4219,6 +4232,7 @@ void HtmlGenerator::generateDetailedQmlMember(const Node *node,
     generateAlsoList(node, marker);
     out() << "</div>";
     out() << "</div>";
+    generateExtractionMark(node, EndMark);
 }
 
 /*!
@@ -4457,6 +4471,40 @@ void HtmlGenerator::generatePageIndex(const QString& fileName, CodeMarker* marke
     file.close();
 }
 
+void HtmlGenerator::generateExtractionMark(const Node *node, ExtractionMarkType markType)
+{
+    if (markType != EndMark) {
+        out() << "<!-- $$$" + node->name();
+        if (markType == MemberMark) {
+            if (node->type() == Node::Function) {
+                const FunctionNode *func = static_cast<const FunctionNode *>(node);
+                if (!func->associatedProperty()) {
+                    if (func->overloadNumber() == 1)
+                        out() << "[overload1]";
+                    out() << "$$$" + func->name() + func->rawParameters().remove(' ');
+                }
+            } else if (node->type() == Node::Property) {
+                const PropertyNode *prop = static_cast<const PropertyNode *>(node);
+                out() << "-prop";
+                const NodeList &list = prop->functions();
+                foreach (const Node *propFuncNode, list) {
+                    if (propFuncNode->type() == Node::Function) {
+                        const FunctionNode *func = static_cast<const FunctionNode *>(propFuncNode);
+                        out() << "$$$" + func->name() + func->rawParameters().remove(' ');
+                    }
+                }
+            }
+        } else if (markType == BriefMark) {
+            out() << "-brief";
+        } else if (markType == DetailedDescriptionMark) {
+            out() << "-description";
+        }
+        out() << " -->\n";
+    } else {
+        out() << "<!-- @@@" + node->name() + " -->\n";
+    }
+}
+
 #endif
 
 #if 0 // fossil removed for new doc format MWS 19/04/2010
diff --git a/tools/qdoc3/htmlgenerator.h b/tools/qdoc3/htmlgenerator.h
index 80341de..c8ede63 100644
--- a/tools/qdoc3/htmlgenerator.h
+++ b/tools/qdoc3/htmlgenerator.h
@@ -123,6 +123,12 @@ class HtmlGenerator : public PageGenerator
 
  private:
     enum SubTitleSize { SmallSubTitle, LargeSubTitle };
+    enum ExtractionMarkType {
+        BriefMark,
+        DetailedDescriptionMark,
+        MemberMark,
+        EndMark
+    };
 
     const QPair<QString,QString> anchorForNode(const Node *node);
     const Node *findNodeForTarget(const QString &target, 
@@ -268,6 +274,7 @@ class HtmlGenerator : public PageGenerator
                               CodeMarker* marker) const;
     void generatePageIndex(const QString& fileName, 
                            CodeMarker* marker) const;
+    void generateExtractionMark(const Node *node, ExtractionMarkType markType);
 
 #if 0
     NavigationBar currentNavigationBar;
diff --git a/tools/qdoc3/node.cpp b/tools/qdoc3/node.cpp
index b077074..af129ed 100644
--- a/tools/qdoc3/node.cpp
+++ b/tools/qdoc3/node.cpp
@@ -1246,6 +1246,24 @@ QStringList FunctionNode::parameterNames() const
 }
 
 /*!
+  Returns a raw list of parameters. If \a names is true, the
+  names are included. If \a values is true, the default values
+  are included, if any are present.
+ */
+QString FunctionNode::rawParameters(bool names, bool values) const
+{
+    QString raw;
+    foreach (const Parameter &parameter, parameters()) {
+        raw += parameter.leftType() + parameter.rightType();
+        if (names)
+            raw += parameter.name();
+        if (values)
+            raw += parameter.defaultValue();
+    }
+    return raw;
+}
+
+/*!
   Returns the list of reconstructed parameters. If \a values
   is true, the default values are included, if any are present.
  */
diff --git a/tools/qdoc3/node.h b/tools/qdoc3/node.h
index e9f2d74..121b818 100644
--- a/tools/qdoc3/node.h
+++ b/tools/qdoc3/node.h
@@ -616,6 +616,7 @@ class FunctionNode : public LeafNode
     int numOverloads() const;
     const QList<Parameter>& parameters() const { return params; }
     QStringList parameterNames() const;
+    QString rawParameters(bool names = false, bool values = false) const;
     const FunctionNode* reimplementedFrom() const { return rf; }
     const QList<FunctionNode*> &reimplementedBy() const { return rb; }
     const PropertyNode* associatedProperty() const { return ap; }
-- 
cgit v0.12