qdoc: Add an auto-generated note in \qmlsignal documentation

Construct the signal handler name and generate a note for it.
This eliminates the need to maintain such notes in the source.

Remove the hard-coded notes from the test source (but not from
the expected output data).

[ChangeLog][qdoc] QDoc now generates a note for the name of
the corresponding handler in \qmlsignal documentation.

Task-number: QTBUG-37355
Change-Id: Ia3ab98be909a41bde619224c9a616cb8704e258a
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

4 files changed, 28 insertions, 5 deletions

diff --git a/src/qdoc/docbookgenerator.cpp b/src/qdoc/docbookgenerator.cpp
index e8cc2c859..063065511 100644
--- a/src/qdoc/docbookgenerator.cpp
+++ b/src/qdoc/docbookgenerator.cpp
@@ -2116,6 +2116,8 @@ void DocBookGenerator::generateBody(const Node *node)
         }
 
         if (fn) {
+            if (fn->isQmlSignal())
+                generateAddendum(node, QmlSignalHandler);
             if (fn->isPrivateSignal())
                 generateAddendum(node, PrivateSignal);
             if (fn->isInvokable())
@@ -3426,6 +3428,19 @@ void DocBookGenerator::generateAddendum(const Node *node, Addendum type, CodeMar
             "This is a private signal. It can be used in signal connections but "
             "cannot be emitted by the user.");
         break;
+    case QmlSignalHandler:
+    {
+        QString handler(node->name());
+        handler[0] = handler[0].toTitleCase();
+        handler.prepend(QLatin1String("on"));
+        writer->writeStartElement(dbNamespace, "para");
+        writer->writeCharacters("The corresponding handler is ");
+        writer->writeTextElement(dbNamespace, "code", handler);
+        writer->writeCharacters(".");
+        writer->writeEndElement(); // para
+        newLine();
+        break;
+    }
     case AssociatedProperties:
     {
         if (!node->isFunction())
diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp
index f8fb9ad02..abf0602df 100644
--- a/src/qdoc/generator.cpp
+++ b/src/qdoc/generator.cpp
@@ -829,6 +829,8 @@ void Generator::generateBody(const Node *node, CodeMarker *marker)
         }
 
         if (fn) {
+            if (fn->isQmlSignal())
+                generateAddendum(node, QmlSignalHandler, marker);
             if (fn->isPrivateSignal())
                 generateAddendum(node, PrivateSignal, marker);
             if (fn->isInvokable())
@@ -1373,6 +1375,16 @@ void Generator::generateAddendum(const Node *node, Addendum type, CodeMarker *ma
         text << "This is a private signal. It can be used in signal connections "
                 "but cannot be emitted by the user.";
         break;
+    case QmlSignalHandler:
+    {
+        QString handler(node->name());
+        handler[0] = handler[0].toTitleCase();
+        handler.prepend(QLatin1String("on"));
+        text << "The corresponding handler is "
+             << Atom(Atom::FormattingLeft, ATOM_FORMATTING_TELETYPE) << handler
+             << Atom(Atom::FormattingRight, ATOM_FORMATTING_TELETYPE) << ".";
+        break;
+    }
     case AssociatedProperties:
     {
         if (!node->isFunction())
diff --git a/src/qdoc/generator.h b/src/qdoc/generator.h
index d72a77bd1..f12aff933 100644
--- a/src/qdoc/generator.h
+++ b/src/qdoc/generator.h
@@ -53,7 +53,7 @@ class Generator
 
 public:
     enum ListType { Generic, Obsolete };
-    enum Addendum { Invokable, PrivateSignal, AssociatedProperties };
+    enum Addendum { Invokable, PrivateSignal, QmlSignalHandler, AssociatedProperties };
 
     Generator();
     virtual ~Generator();
diff --git a/tests/auto/qdoc/generatedoutput/testdata/qml/type.cpp b/tests/auto/qdoc/generatedoutput/testdata/qml/type.cpp
index 10a310a87..bf04bdb43 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/qml/type.cpp
+++ b/tests/auto/qdoc/generatedoutput/testdata/qml/type.cpp
@@ -92,14 +92,10 @@
     \qmlsignal Type::completed(int status)
 
     This signal is emitted when the operation completed with \a status.
-
-    \note The corresponding handler is \c onCompleted.
 */
 
 /*!
     \qmlattachedsignal Type::configured()
 
     This attached signal is emitted when the type was configured.
-
-    \note The corresponding handler is \c onConfigured.
 */