QDoc: Add warning to use of \contentspage commandv5.15.0-beta2

The \contentspage command doesn't produce nav links to the contents page
between the next and previous pages. QDoc hasn't generated these links
in html output since Qt 5.3. Remove the documentation that refers to the
command and add a warning that it should not be used..

Task-number: QTBUG-75170
Change-Id: Ib16fc1cbb1e661a7519ba650e655e209c3b45b68
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

9 files changed, 3 insertions, 44 deletions

diff --git a/src/qdoc/cppcodeparser.cpp b/src/qdoc/cppcodeparser.cpp
index dec081c22..647631c27 100644
--- a/src/qdoc/cppcodeparser.cpp
+++ b/src/qdoc/cppcodeparser.cpp
@@ -33,8 +33,9 @@
 #include "cppcodeparser.h"
 
 #include "config.h"
-#include "qdocdatabase.h"
 #include "generator.h"
+#include "loggingcategory.h"
+#include "qdocdatabase.h"
 
 #include <QtCore/qdebug.h>
 #include <QtCore/qfile.h>
@@ -559,6 +560,7 @@ void CppCodeParser::processMetaCommand(const Doc &doc, const QString &command,
             }
         }
     } else if (command == COMMAND_CONTENTSPAGE) {
+        qCWarning(lcQdoc, "(qdoc) The \\contentspage command is obsolete and should not be used.");
         setLink(node, Node::ContentsLink, arg);
     } else if (command == COMMAND_NEXTPAGE) {
         setLink(node, Node::NextLink, arg);
diff --git a/src/qdoc/doc/files/basicqt.qdoc.sample b/src/qdoc/doc/files/basicqt.qdoc.sample
index ce8df096f..1243387b2 100644
--- a/src/qdoc/doc/files/basicqt.qdoc.sample
+++ b/src/qdoc/doc/files/basicqt.qdoc.sample
@@ -1,6 +1,5 @@
  /*!
      \page basicqt.html
-     \contentspage {Basic Qt} {Contents}
      \nextpage Getting Started
 
      \indexpage Index
@@ -24,7 +23,6 @@
  /*!
     \page gettingstarted.html
     \previouspage Basic Qt
-    \contentspage {Basic Qt} {Contents}
     \nextpage Creating Dialogs
 
     \indexpage Index
@@ -40,7 +38,6 @@
 / *!
     \page creatingdialogs.html
     \previouspage Getting Started
-    \contentspage {Basic Qt} {Contents}
 
     \indexpage Index
     \startpage Basic Qt
diff --git a/src/qdoc/doc/qa-pages.qdoc b/src/qdoc/doc/qa-pages.qdoc
index c69b1cdc6..1e3ca19f4 100644
--- a/src/qdoc/doc/qa-pages.qdoc
+++ b/src/qdoc/doc/qa-pages.qdoc
@@ -28,7 +28,6 @@
 /*!
     \page 28-qdoc-qa-pages.html
     \previouspage The QDoc Configuration File
-    \contentspage QDoc Manual
     \nextpage QDoc Manual
 
     \title QA Pages
diff --git a/src/qdoc/doc/qdoc-manual-cmdindex.qdoc b/src/qdoc/doc/qdoc-manual-cmdindex.qdoc
index 672c2e409..77a3266fb 100644
--- a/src/qdoc/doc/qdoc-manual-cmdindex.qdoc
+++ b/src/qdoc/doc/qdoc-manual-cmdindex.qdoc
@@ -28,7 +28,6 @@
 /*!
     \page 27-qdoc-commands-alphabetical.html
     \previouspage Introduction to QDoc
-    \contentspage QDoc Manual
     \nextpage Topic Commands
 
     \title Command Index
@@ -49,7 +48,6 @@
     \li \l {class-command} {\\class}
     \li \l {code-command} {\\code}
     \li \l {codeline-command} {\\codeline}
-    \li \l {contentspage-command} {\\contentspage}
     \li \l {default-command} {\\default}
     \li \l {div-command} {\\div}
     \li \l {dots-command} {\\dots}
diff --git a/src/qdoc/doc/qdoc-manual-contextcmds.qdoc b/src/qdoc/doc/qdoc-manual-contextcmds.qdoc
index f020035d3..3d69e76a6 100644
--- a/src/qdoc/doc/qdoc-manual-contextcmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-contextcmds.qdoc
@@ -28,7 +28,6 @@
 /*!
     \page 14-qdoc-commands-contextcommands.html
     \previouspage Topic Commands
-    \contentspage QDoc Manual
     \nextpage Document Navigation
 
     \title Context Commands
@@ -47,7 +46,6 @@
 
     \list
       \li \l {abstract-command} {\\abstract}
-      \li \l {contentspage-command}{\\contentspage},
       \li \l {ingroup-command}{\\ingroup},
       \li \l {inherits-command}{\\inherits},
       \li \l {inmodule-command}{\\inmodule},
@@ -74,7 +72,6 @@
 /*!
     \page 15-qdoc-commands-navigation.html
     \previouspage Context Commands
-    \contentspage QDoc Manual
     \nextpage Status
 
     \title Document Navigation
@@ -169,20 +166,11 @@
     documentation. The generated link type tells browsers and search
     engines which document is considered by the author to be the
     starting point of the collection.
-
-    \target contentspage-command
-    \section2 \\contentspage
-
-    The \\contentspage command links the current page to a table of
-    contents page. The command follows the same syntax and argument
-    convention as the \l {previouspage-command} {\\previouspage}
-    command.
 */
 
 /*!
     \page 16-qdoc-commands-status.html
     \previouspage Document Navigation
-    \contentspage QDoc Manual
     \nextpage Thread Support
 
     \title Status
@@ -441,7 +429,6 @@
 /*!
     \page 17-qdoc-commands-thread.html
     \previouspage Status
-    \contentspage QDoc Manual
     \nextpage Relating Things
 
     \title Thread Support
@@ -621,7 +608,6 @@
 /*!
     \page 18-qdoc-commands-relating.html
     \previouspage Thread Support
-    \contentspage QDoc Manual
     \nextpage Grouping Things
 
     \title Relating Things
@@ -808,7 +794,6 @@
 /*!
     \page 19-qdoc-commands-grouping.html
     \previouspage Relating Things
-    \contentspage QDoc Manual
     \nextpage Naming Things
 
     \title Grouping Things
@@ -890,7 +875,6 @@
 /*!
     \page 20-qdoc-commands-namingthings.html
     \previouspage Grouping Things
-    \contentspage QDoc Manual
     \nextpage Markup Commands
 
     \title Naming Things
diff --git a/src/qdoc/doc/qdoc-manual-intro.qdoc b/src/qdoc/doc/qdoc-manual-intro.qdoc
index 7ea3f1e36..a943863a6 100644
--- a/src/qdoc/doc/qdoc-manual-intro.qdoc
+++ b/src/qdoc/doc/qdoc-manual-intro.qdoc
@@ -27,7 +27,6 @@
 
 /*!
     \page 01-qdoc-manual.html
-    \contentspage QDoc Manual
     \previouspage QDoc Manual
     \nextpage Command Index
 
diff --git a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
index 386501cd3..6fc16c9e1 100644
--- a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -27,7 +27,6 @@
 
 /*!
     \page 03-qdoc-commands-markup.html
-    \contentspage QDoc Manual
     \previouspage Naming Things
     \nextpage Text Markup
 
@@ -109,7 +108,6 @@
 
 /*!
     \page 04-qdoc-commands-textmarkup.html
-    \contentspage QDoc Manual
     \previouspage Markup Commands
     \nextpage Document Structure
 
@@ -659,7 +657,6 @@
 /*!
     \page 05-qdoc-commands-documentstructure.html
     \previouspage Text Markup
-    \contentspage QDoc Manual
     \nextpage Including Code Inline
 
     \title Document Structure
@@ -858,7 +855,6 @@
 /*!
     \page 06-qdoc-commands-includecodeinline.html
     \previouspage Document Structure
-    \contentspage QDoc Manual
     \nextpage Including External Code
 
     \title Including Code Inline
@@ -1091,7 +1087,6 @@
 /*!
     \page 07-0-qdoc-commands-includingexternalcode.html
     \previouspage Including Code Inline
-    \contentspage QDoc Manual
     \nextpage Creating Links
 
     \title Including External Code
@@ -1722,7 +1717,6 @@
 /*!
     \page 08-qdoc-commands-creatinglinks.html
     \previouspage Including External Code
-    \contentspage QDoc Manual
     \nextpage Including Images
 
     \title Creating Links
@@ -2119,7 +2113,6 @@
 /*!
     \page 09-qdoc-commands-includingimages.html
     \previouspage Creating Links
-    \contentspage QDoc Manual
     \nextpage Tables and Lists
 
     \title Including Images
@@ -2316,7 +2309,6 @@
 /*!
     \page 10-qdoc-commands-tablesandlists.html
     \previouspage Including Images
-    \contentspage QDoc Manual
     \nextpage Special Content
 
     \title Tables and Lists
@@ -2857,7 +2849,6 @@
 /*!
     \page 11-qdoc-commands-specialcontent.html
     \previouspage Tables and Lists
-    \contentspage QDoc Manual
     \nextpage Miscellaneous
 
     \title Special Content
@@ -3292,7 +3283,6 @@
 /*!
     \page 12-0-qdoc-commands-miscellaneous.html
     \previouspage Special Content
-    \contentspage QDoc Manual
     \nextpage The QDoc Configuration File
 
     \title Miscellaneous
diff --git a/src/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
index 62ac13c28..d15fd5515 100644
--- a/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
+++ b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
@@ -28,7 +28,6 @@
 /*!
     \page 21-0-qdoc-configuration.html
     \previouspage Miscellaneous
-    \contentspage QDoc Manual
     \nextpage Generic Configuration Variables
 
     \title The QDoc Configuration File
@@ -151,7 +150,6 @@
 /*!
     \page 22-qdoc-configuration-generalvariables.html
     \previouspage The QDoc Configuration File
-    \contentspage QDoc Manual
     \nextpage Creating Help Project Files
 
     \title Generic Configuration Variables
@@ -1317,7 +1315,6 @@
 /*!
     \page 22-creating-help-project-files.html
     \previouspage Generic Configuration Variables
-    \contentspage QDoc Manual
     \nextpage C++ Specific Configuration Variables
 
     \title Creating Help Project Files
@@ -1451,7 +1448,6 @@
 /*!
     \page 23-qdoc-configuration-cppvariables.html
     \previouspage Creating Help Project Files
-    \contentspage QDoc Manual
     \nextpage Format-specific Configuration Variables
 
     \title C++ Specific Configuration Variables
@@ -1562,7 +1558,6 @@
 /*!
     \page 24-qdoc-configuration-htmlvariables.html
     \previouspage C++ Specific Configuration Variables
-    \contentspage QDoc Manual
     \nextpage Supporting Derived Projects
 
     \keyword HTML Specific Configuration Variables
@@ -1713,7 +1708,6 @@
 /*!
     \page 25-qdoc-configuration-derivedprojects.html
     \previouspage Format-specific Configuration Variables
-    \contentspage QDoc Manual
     \nextpage Example Manifest Files
 
     \title Supporting Derived Projects
@@ -1871,7 +1865,6 @@
 /*!
     \page 26-qdoc-configuration-example-manifest-files.html
     \previouspage Supporting Derived Projects
-    \contentspage QDoc Manual
 
     \title Example Manifest Files
 
@@ -1953,7 +1946,6 @@
 /*!
     \page 21-1-minimum-qdocconf.html
     \previouspage qtgui.qdocconf
-    \contentspage QDoc Manual
     \nextpage The QDoc Configuration File
 
     \title minimum.qdocconf
@@ -1964,7 +1956,6 @@
 /*!
     \page 21-2-qtgui-qdocconf.html
     \previouspage Supporting Derived Projects
-    \contentspage QDoc Manual
     \nextpage minimum.qdocconf
 
     \title qtgui.qdocconf
diff --git a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
index cdd0c9aeb..e7405e442 100644
--- a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
@@ -28,7 +28,6 @@
 /*!
     \page 13-qdoc-commands-topics.html
     \previouspage Command Index
-    \contentspage QDoc Manual
     \nextpage Context Commands
 
     \title Topic Commands