Documentation: Show an example for each overloaded signal

The new connection syntax is a bit tricky to use, when the signal or
the slot is overloaded, because one must explicitly cast to the
correct signal type.

This patch adds an example to the documentation of each overloaded
signal. The example shows how to do the cast to the correct signal
type.

Change-Id: Ifc9f28d05c2ae126a674d2ca5887935fc59cd83b
Reviewed-by: Olivier Goffart (Woboq GmbH) <ogoffart@woboq.com>

src/tools/qdoc/generator.cpp

@@ -1478,7 +1478,76 @@ void Generator::generateThreadSafeness(const Node *node, CodeMarker *marker)
 }
 
 /*!
-  Traverses the current tree to generate all the documentation.
+    If the node is an overloaded signal, and a node with an example on how to connect to it
+ */
+void Generator::generateOverloadedSignal(const Node* node, CodeMarker* marker)
+{
+    if (node->type() != Node::Function)
+        return;
+    const FunctionNode *func = static_cast<const FunctionNode *>(node);
+    if (func->metaness() != FunctionNode::Signal)
+        return;
+    if (node->parent()->overloads(node->name()).count() <= 1)
+        return;
+
+
+    // Compute a friendly name for the object of that instance.
+    // e.g:  "QAbstractSocket" -> "abstractSocket"
+    QString objectName = node->parent()->name();
+    if (objectName.size() >= 2) {
+        if (objectName[0] == 'Q')
+            objectName = objectName.mid(1);
+        objectName[0] = objectName[0].toLower();
+    }
+
+
+    // We have an overloaded signal, show an example
+    QString code = "connect(" + objectName + ", static_cast<" + func->returnType()
+        + "(" + func->parent()->name() + "::*)(";
+    for (int i = 0; i < func->parameters().size(); ++i) {
+        if (i != 0)
+            code += ", ";
+        const Parameter &p = func->parameters().at(i);
+        code += p.leftType() + p.rightType();
+    }
+
+    code += ")";
+    if (func->isConst())
+        code += " const";
+    code += ">(&" +  func->parent()->name() + "::" + func->name() + "),\n    [=](";
+
+    for (int i = 0; i < func->parameters().size(); ++i) {
+        if (i != 0)
+            code += ", ";
+        const Parameter &p = func->parameters().at(i);
+        code += p.leftType();
+        if (code[code.size()-1].isLetterOrNumber())
+            code += " ";
+        code += p.name()  + p.rightType();
+    }
+
+    code += "){ /* ... */ });";
+
+    Text text;
+    text << Atom::ParaLeft
+         << Atom(Atom::FormattingLeft,ATOM_FORMATTING_BOLD)
+         << "Note:"
+         << Atom(Atom::FormattingRight,ATOM_FORMATTING_BOLD)
+         << "Signal "
+         << Atom(Atom::FormattingLeft,ATOM_FORMATTING_ITALIC)
+         << node->name()
+         << Atom(Atom::FormattingRight,ATOM_FORMATTING_ITALIC)
+         << " is overloaded in this class. "
+            "To connect to this one using the function pointer syntax, you must "
+            "specify the signal type in a static cast, as shown in this example:"
+          << Atom(Atom::Code, marker->markedUpCode(code, node, func->location()));
+
+    generateText(text, node, marker);
+}
+
+
+/*!
+  Traverses the database recursivly to generate all the documentation.
  */
 void Generator::generateDocs()
 {

src/tools/qdoc/generator.h

@@ -161,6 +161,7 @@ protected:
     void generateThreadSafeness(const Node *node, CodeMarker *marker);
     QString getMetadataElement(const Aggregate* inner, const QString& t);
     QStringList getMetadataElements(const Aggregate* inner, const QString& t);
+    void generateOverloadedSignal(const Node *node, CodeMarker *marker);
     QString indent(int level, const QString& markedCode);
     QTextStream& out();
     QString outFileName();

src/tools/qdoc/htmlgenerator.cpp

@@ -3957,6 +3957,7 @@ void HtmlGenerator::generateDetailedMember(const Node *node,
 
     generateStatus(node, marker);
     generateBody(node, marker);
+    generateOverloadedSignal(node, marker);
     generateThreadSafeness(node, marker);
     generateSince(node, marker);