qdoc: Document a namespace in multiple modules

qdoc didn't handle this. This update fixes most of what was wrong,
but tuning the details of the namespace reference pages might follow.
We have namespace Qt as an example. Most of the elements in the Qt
namespace are in QtCore, but a few functions are declared in QtGui.
Before this update, qdoc used the hack of using #ifdef to remove the
declarations from qtextdocument.h in QtGui and .cpp and then added
them back into qtnamespace.h and .cpp in QtCore.

Now that hack is no longer necessary. The functions in the Qt namespace
that are declared in QtGui are documented there, but the documentation
is linked to from the namespace reference page, which remains in QtCore.
That is, only one \namespace command is used to document the Qt namespace,
and it appears in qnamespace.qdoc where it always did, but the documentation
for the Qt namespace functions declared in QtGui is now appears in
qtextdocument.cpp where it belongs.

This also allows qdoc to report when a namespace contains elements that are
public and documented, but the namespace itself is not documented, which was
not possible before this change. qdoc also reports if a namespace is documented
in more than one module. That is, for example, when \namespace Qt is used in
both QtCore and QtGui.

Note that this change will increase the number of qdoc warnings in
QtBase, but the new warnings are expacted.

Change-Id: If978a59209b7b2ae90713d3ae809ae03361df72f
Task-number: QTBUG-67267
Reviewed-by: Martin Smith <martin.smith@qt.io>

1 files changed, 11 insertions, 3 deletions

diff --git a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
index b2ae67dbf..05e7b331b 100644
--- a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
@@ -865,9 +865,9 @@
     \section1 \\namespace
 
     The \\namespace command is for documenting the contents of the C++
-    namespace named as its argument. The documentation outline QDoc
-    generates for a namespace is similar to the outline it generates
-    for a C++ class.
+    namespace named as its argument. The reference page QDoc generates
+    for a namespace is similar to the reference page it generates for a
+    C++ class.
 
     \code
     / *!
@@ -914,6 +914,14 @@
                ...
            \endquotation
 
+    Note that in C++, a particular namespace can be used in more
+    than one module, but when C++ elements from different modules
+    are declared in the same namespace, the namespace itself must
+    be documented in one module only. For example, namespace Qt in
+    the example above contains types and functions from both QtCore
+    and QtGui, but it is documented with the \\namespace command
+    only in QtCore.
+
     \target page-command
     \section1 \\page