doc: Output a clearer "All functions in this class are..." statement.

Task-number: 189232

1 files changed, 129 insertions, 39 deletions

diff --git a/tools/qdoc3/generator.cpp b/tools/qdoc3/generator.cpp
index 00831d1..e97b7f2 100644
--- a/tools/qdoc3/generator.cpp
+++ b/tools/qdoc3/generator.cpp
@@ -68,10 +68,12 @@ QStringList Generator::imageDirs;
 QString Generator::outDir;
 QString Generator::project;
 
-static Text stockLink(const QString &target)
+static void singularPlural(Text& text, const NodeList& nodes)
 {
-    return Text() << Atom(Atom::Link, target) << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
-                  << target << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK);
+    if (nodes.count() == 1)
+        text << " is";
+    else
+        text << " are";
 }
 
 Generator::Generator()
@@ -775,64 +777,138 @@ void Generator::generateThreadSafeness(const Node *node, CodeMarker *marker)
 {
     Text text;
     Text theStockLink;
-    Node::ThreadSafeness parent = node->parent()->inheritedThreadSafeness();
+    Node::ThreadSafeness threadSafeness = node->threadSafeness();
+
+    Text rlink;
+    rlink << Atom(Atom::Link,"reentrant")
+          << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
+          << "reentrant"
+          << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK);
 
-    switch (node->threadSafeness()) {
+    Text tlink;
+    tlink << Atom(Atom::Link,"thread-safe")
+          << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
+          << "thread-safe"
+          << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK);
+
+    switch (threadSafeness) {
     case Node::UnspecifiedSafeness:
         break;
     case Node::NonReentrant:
-        text << Atom::ParaLeft << Atom(Atom::FormattingLeft, ATOM_FORMATTING_BOLD) << "Warning:"
-             << Atom(Atom::FormattingRight, ATOM_FORMATTING_BOLD) << " This "
-             << typeString(node) << " is not " << stockLink("reentrant") << "." << Atom::ParaRight;
+        text << Atom::ParaLeft
+             << Atom(Atom::FormattingLeft,ATOM_FORMATTING_BOLD)
+             << "Warning:"
+             << Atom(Atom::FormattingRight,ATOM_FORMATTING_BOLD)
+             << " This "
+             << typeString(node)
+             << " is not "
+             << rlink
+             << "."
+             << Atom::ParaRight;
         break;
     case Node::Reentrant:
     case Node::ThreadSafe:
-        text << Atom::ParaLeft << Atom(Atom::FormattingLeft, ATOM_FORMATTING_BOLD);
-        if (parent == Node::ThreadSafe) {
-            text << "Warning:";
-        } else {
-            text << "Note:";
-        }
-        text << Atom(Atom::FormattingRight, ATOM_FORMATTING_BOLD) << " ";
-
-        if (node->threadSafeness() == Node::ThreadSafe)
-            theStockLink = stockLink("thread-safe");
-        else
-            theStockLink = stockLink("reentrant");
+        text << Atom::ParaLeft
+             << Atom(Atom::FormattingLeft,ATOM_FORMATTING_BOLD)
+             << "Note:"
+             << Atom(Atom::FormattingRight,ATOM_FORMATTING_BOLD)
+             << " ";
 
         if (node->isInnerNode()) {
-            const InnerNode *innerNode = static_cast<const InnerNode *>(node);
-            text << "All the functions in this " << typeString(node) << " are "
-                 << theStockLink;
-
-            NodeList except;
+            const InnerNode* innerNode = static_cast<const InnerNode*>(node);
+            text << "All functions in this "
+                 << typeString(node)
+                 << " are ";
+            if (threadSafeness == Node::ThreadSafe)
+                text << tlink;
+            else
+                text << rlink;
+
+            bool exceptions = false;
+            NodeList reentrant;
+            NodeList threadsafe;
+            NodeList nonreentrant;
             NodeList::ConstIterator c = innerNode->childNodes().begin();
             while (c != innerNode->childNodes().end()) {
-                if ((*c)->threadSafeness() != Node::UnspecifiedSafeness)
-                    except.append(*c);
+                switch ((*c)->threadSafeness()) {
+                case Node::Reentrant:
+                    reentrant.append(*c);
+                    if (threadSafeness == Node::ThreadSafe)
+                        exceptions = true;
+                    break;
+                case Node::ThreadSafe:
+                    threadsafe.append(*c);
+                    if (threadSafeness == Node::Reentrant)
+                        exceptions = true;
+                    break;
+                case Node::NonReentrant:
+                    nonreentrant.append(*c);
+                    exceptions = true;
+                    break;
+                default:
+                    break;
+                }
                 ++c;
             }
-            if (except.isEmpty()) {
+            if (!exceptions) 
                 text << ".";
+            else if (threadSafeness == Node::Reentrant) {
+                if (nonreentrant.isEmpty()) {
+                    if (!threadsafe.isEmpty()) {
+                        text << ", but ";
+                        appendFullNames(text,threadsafe,innerNode,marker);
+                        singularPlural(text,threadsafe);
+                        text << " also " << tlink << ".";
+                    }
+                    else
+                        text << ".";
+                }
+                else {
+                    text << ", except for ";
+                    appendFullNames(text,nonreentrant,innerNode,marker);
+                    text << ", which";
+                    singularPlural(text,nonreentrant);
+                    text << " nonreentrant.";
+                    if (!threadsafe.isEmpty()) {
+                        text << " ";
+                        appendFullNames(text,threadsafe,innerNode,marker);
+                        singularPlural(text,threadsafe);
+                        text << " " << tlink << ".";
+                    }
+                }
             }
-            else {
-                text << ", except ";
-
-                NodeList::ConstIterator e = except.begin();
-                int index = 0;
-                while (e != except.end()) {
-                    appendFullName(text, *e, innerNode, marker);
-                    text << separator(index++, except.count());
-                    ++e;
+            else { // thread-safe
+                if (!nonreentrant.isEmpty() || !reentrant.isEmpty()) {
+                    text << ", except for ";
+                    if (!reentrant.isEmpty()) {
+                        appendFullNames(text,reentrant,innerNode,marker);
+                        text << ", which";
+                        singularPlural(text,reentrant);
+                        text << " only " << rlink;
+                        if (!nonreentrant.isEmpty())
+                            text << ", and ";
+                    }
+                    if (!nonreentrant.isEmpty()) {
+                        appendFullNames(text,nonreentrant,innerNode,marker);
+                        text << ", which";
+                        singularPlural(text,nonreentrant);
+                        text << " nonreentrant.";
+                    }
+                    text << ".";
                 }
             }
         }
         else {
-            text << "This " << typeString(node) << " is " << theStockLink << ".";
+            text << "This " << typeString(node) << " is ";
+            if (threadSafeness == Node::ThreadSafe)
+                text << tlink;
+            else
+                text << rlink;
+            text << ".";
         }
         text << Atom::ParaRight;
     }
-    generateText(text, node, marker);
+    generateText(text,node,marker);
 }
 
 void Generator::generateSince(const Node *node, CodeMarker *marker)
@@ -966,6 +1042,20 @@ void Generator::appendFullName(Text& text,
          << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK);
 }
 
+void Generator::appendFullNames(Text& text,
+                                const NodeList& nodes,
+                                const Node* relative,
+                                CodeMarker* marker)
+{
+    NodeList::ConstIterator n = nodes.begin();
+    int index = 0;
+    while (n != nodes.end()) {
+        appendFullName(text,*n,relative,marker);
+        text << comma(index++,nodes.count());
+        ++n;
+    }
+}
+
 void Generator::appendSortedNames(Text& text,
                                   const ClassNode *classe,
                                   const QList<RelatedClass> &classes,