qdoc: Properly document "private" signals

When a signal declaration is marked with QSignalPrivate,
This note is included in its documentation: "Note: This
is a private signal. It must not be emitted by the user."

For Notifier signals, [see note] is appended to the signature line,
and the Note is printed below the list.

Change-Id: Ie792894ace56cda47fd9a45af9c732f408ac45f6
Task-number: QTBUG-45535
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>

src/tools/qdoc/cppcodeparser.cpp

@@ -1329,6 +1329,11 @@ bool CppCodeParser::matchParameter(FunctionNode *func)
     QString name;
     CodeChunk defaultValue;
 
+    if (match(Tok_QPrivateSignal)) {
+        func->setPrivateSignal();
+        return true;
+    }
+
     if (!matchDataType(&dataType, &name)) {
         return false;
     }

src/tools/qdoc/generator.cpp

@@ -1249,6 +1249,23 @@ void Generator::generateStatus(const Node *node, CodeMarker *marker)
     generateText(text, node, marker);
 }
 
+/*!
+  Generates a bold line that says:
+  "The signal is private, not emitted by the user.
+  The function is public so the user can pass it to connect()."
+ */
+void Generator::generatePrivateSignalNote(const Node* node, CodeMarker* marker)
+{
+    Text text;
+    text << Atom::ParaLeft
+         << Atom(Atom::FormattingLeft, ATOM_FORMATTING_BOLD)
+         << "Note: "
+         << Atom(Atom::FormattingRight, ATOM_FORMATTING_BOLD)
+         << "This is a private signal. It can be used in signal connections but cannot be emitted by the user."
+         << Atom::ParaRight;
+    generateText(text, node, marker);
+}
+
 /*!
   Generate the documentation for \a relative. i.e. \a relative
   is the node that reporesentas the entity where a qdoc comment

src/tools/qdoc/generator.h

@@ -156,6 +156,7 @@ protected:
                           const QString& tag);
     void generateSince(const Node *node, CodeMarker *marker);
     void generateStatus(const Node *node, CodeMarker *marker);
+    void generatePrivateSignalNote(const Node* node, CodeMarker* marker);
     void generateThreadSafeness(const Node *node, CodeMarker *marker);
     QString getMetadataElement(const InnerNode* inner, const QString& t);
     QStringList getMetadataElements(const InnerNode* inner, const QString& t);

src/tools/qdoc/htmlgenerator.cpp

@@ -3265,6 +3265,7 @@ void HtmlGenerator::generateSectionList(const Section& section,
 {
     bool alignNames = true;
     if (!section.members.isEmpty()) {
+        bool hasPrivateSignals = false;
         bool twoColumn = false;
         if (style == CodeMarker::Subpage) {
             alignNames = false;
@@ -3307,6 +3308,14 @@ void HtmlGenerator::generateSectionList(const Section& section,
                 prefix = prefix.left(section.keys.at(i).indexOf("::")+1);
             }
             generateSynopsis(*m, relative, marker, style, alignNames, &prefix);
+            if ((*m)->isFunction()) {
+                const FunctionNode* fn = static_cast<const FunctionNode*>(*m);
+                if (fn->isPrivateSignal()) {
+                    hasPrivateSignals = true;
+                    if (alignNames)
+                        out() << "</td><td class=\"memItemRight bottomAlign\">[see note below]";
+                }
+            }
             if (alignNames)
                 out() << "</td></tr>\n";
             else
@@ -3321,6 +3330,9 @@ void HtmlGenerator::generateSectionList(const Section& section,
             if (twoColumn)
                 out() << "</td></tr>\n</table></div>\n";
         }
+        if (hasPrivateSignals && alignNames) {
+            generatePrivateSignalNote(relative, marker);
+        }
     }
 
     if (style == CodeMarker::Summary && !section.inherited.isEmpty()) {
@@ -4023,6 +4035,11 @@ void HtmlGenerator::generateDetailedMember(const Node *node,
             generateSectionList(notifiers, node, marker, CodeMarker::Accessors);
         }
     }
+    else if (node->isFunction()) {
+        const FunctionNode* fn = static_cast<const FunctionNode*>(node);
+        if (fn->isPrivateSignal())
+            generatePrivateSignalNote(node, marker);
+    }
     else if (node->type() == Node::Enum) {
         const EnumNode *enume = static_cast<const EnumNode *>(node);
         if (enume->flagsType()) {

src/tools/qdoc/node.cpp

@@ -1804,6 +1804,7 @@ FunctionNode::FunctionNode(InnerNode *parent, const QString& name)
       ove(false),
       reimp(false),
       attached_(false),
+      privateSignal_(false),
       rf(0),
       ap(0)
 {
@@ -1824,6 +1825,7 @@ FunctionNode::FunctionNode(Type type, InnerNode *parent, const QString& name, bo
       ove(false),
       reimp(false),
       attached_(attached),
+      privateSignal_(false),
       rf(0),
       ap(0)
 {

src/tools/qdoc/node.h

@@ -928,6 +928,8 @@ public:
     virtual QString logicalModuleIdentifier() const Q_DECL_OVERRIDE {
         return parent()->logicalModuleIdentifier();
     }
+    bool isPrivateSignal() const { return privateSignal_; }
+    void setPrivateSignal() { privateSignal_ = true; }
 
     void debug() const;
 
@@ -946,6 +948,7 @@ private:
     bool ove : 1;
     bool reimp: 1;
     bool attached_: 1;
+    bool privateSignal_: 1;
     QList<Parameter> params;
     const FunctionNode* rf;
     const PropertyNode* ap;

src/tools/qdoc/tokenizer.cpp

@@ -78,7 +78,8 @@ static const char *kwords[] = {
     "QT3_SUPPORT",
     "QT3_SUPPORT_CONSTRUCTOR",
     "QT3_MOC_SUPPORT",
-    "QDOC_PROPERTY"
+    "QDOC_PROPERTY",
+    "QPrivateSignal"
 };
 
 static const int KwordHashTableSize = 4096;

src/tools/qdoc/tokenizer.h

@@ -74,8 +74,8 @@ enum { Tok_Eoi, Tok_Ampersand, Tok_Aster, Tok_Caret, Tok_LeftParen,
        Tok_Q_DECLARE_FLAGS, Tok_Q_SIGNALS, Tok_Q_SLOTS, Tok_QT_COMPAT,
        Tok_QT_COMPAT_CONSTRUCTOR, Tok_QT_DEPRECATED, Tok_QT_MOC_COMPAT,
        Tok_QT_MODULE, Tok_QT3_SUPPORT, Tok_QT3_SUPPORT_CONSTRUCTOR,
-       Tok_QT3_MOC_SUPPORT, Tok_QDOC_PROPERTY,
+       Tok_QT3_MOC_SUPPORT, Tok_QDOC_PROPERTY, Tok_QPrivateSignal,
-       Tok_FirstKeyword = Tok_char, Tok_LastKeyword = Tok_QDOC_PROPERTY };
+       Tok_FirstKeyword = Tok_char, Tok_LastKeyword = Tok_QPrivateSignal };
 
 /*
   The Tokenizer class implements lexical analysis of C++ source