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

Task-number: 189232

4 files changed, 156 insertions, 53 deletions

diff --git a/tools/qdoc3/generator.cpp b/tools/qdoc3/generator.cpp
index 00831d1f4f..e97b7f275b 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,
diff --git a/tools/qdoc3/generator.h b/tools/qdoc3/generator.h
index 08b857b973..cdc4c293fd 100644
--- a/tools/qdoc3/generator.h
+++ b/tools/qdoc3/generator.h
@@ -154,6 +154,10 @@ class Generator
                         const Node *apparentNode,
                         const QString& fullName,
                         const Node *actualNode);
+    void appendFullNames(Text& text,
+                         const NodeList& nodes,
+                         const Node* relative,
+                         CodeMarker* marker);
     void appendSortedNames(Text& text, 
                            const ClassNode *classe,
                            const QList<RelatedClass> &classes,
diff --git a/tools/qdoc3/separator.cpp b/tools/qdoc3/separator.cpp
index 8f27f90138..60674be759 100644
--- a/tools/qdoc3/separator.cpp
+++ b/tools/qdoc3/separator.cpp
@@ -48,22 +48,30 @@
 
 QT_BEGIN_NAMESPACE
 
-QString separator( int index, int count )
+QString separator(int index, int count)
 {
-    if ( index == count - 1 )
-	return tr( ".", "terminator" );
+    if (index == count - 1)
+	return tr(".", "terminator");
+    if (count == 2)
+	return tr(" and ", "separator when N = 2");
+    if (index == 0)
+        return tr(", ", "first separator when N > 2");
+    if (index < count - 2)
+        return tr(", ", "general separator when N > 2");
+    return tr(", and ", "last separator when N > 2");
+}
 
-    if ( count == 2 ) {
-	return tr( " and ", "separator when N = 2" );
-    } else {
-	if ( index == 0 ) {
-	    return tr( ", ", "first separator when N > 2" );
-	} else if ( index < count - 2 ) {
-	    return tr( ", ", "general separator when N > 2" );
-	} else {
-	    return tr( ", and ", "last separator when N > 2" );
-	}
-    }
+QString comma(int index, int count)
+{
+    if (index == count - 1)
+    	return QString("");
+    if (count == 2)
+	return tr(" and ", "separator when N = 2");
+    if (index == 0) 
+        return tr(", ", "first separator when N > 2");
+    if (index < count - 2) 
+        return tr(", ", "general separator when N > 2");
+    return tr(", and ", "last separator when N > 2");
 }
 
 QT_END_NAMESPACE
diff --git a/tools/qdoc3/separator.h b/tools/qdoc3/separator.h
index 70ba6245a3..2336d9474a 100644
--- a/tools/qdoc3/separator.h
+++ b/tools/qdoc3/separator.h
@@ -51,6 +51,7 @@
 QT_BEGIN_NAMESPACE
 
 QString separator( int index, int count );
+QString comma( int index, int count );
 
 QT_END_NAMESPACE