qdoc: Update documentation of \qmlabstract

The \qmlabstract command was missing from the qdoc user manual, and
qdoc was still allowing the \abstract command to be used for marking
up the abstract of a scientific paper. The \abstract command is now
made a synonym of \qmlabstract, and they are both added to the qdoc
user manual.

Change-Id: I003ac50b8dabbf037f18d9ea3e6d88a12d69bf5f
Task-number: QTBUG-46003
Reviewed-by: Venugopal Shivashankar <[email protected]>
Reviewed-by: Martin Smith <[email protected]>

11 files changed, 40 insertions, 63 deletions

diff --git a/src/tools/qdoc/atom.cpp b/src/tools/qdoc/atom.cpp
index ebbe685985c..f50f401c5b6 100644
--- a/src/tools/qdoc/atom.cpp
+++ b/src/tools/qdoc/atom.cpp
@@ -66,8 +66,6 @@ QT_BEGIN_NAMESPACE
 
 /*! \enum Atom::AtomType
 
-  \value AbstractLeft
-  \value AbstractRight
   \value AnnotatedList
   \value AutoLink
   \value BaseName
@@ -149,8 +147,6 @@ static const struct {
     const char *english;
     int no;
 } atms[] = {
-    { "AbstractLeft", Atom::AbstractLeft },
-    { "AbstractRight", Atom::AbstractRight },
     { "AnnotatedList", Atom::AnnotatedList },
     { "AutoLink", Atom::AutoLink },
     { "BaseName", Atom::BaseName },
diff --git a/src/tools/qdoc/atom.h b/src/tools/qdoc/atom.h
index dae106a7425..86b8ba7b3c6 100644
--- a/src/tools/qdoc/atom.h
+++ b/src/tools/qdoc/atom.h
@@ -47,8 +47,6 @@ class Atom
 {
 public:
     enum AtomType {
-        AbstractLeft,
-        AbstractRight,
         AnnotatedList,
         AutoLink,
         BaseName,
diff --git a/src/tools/qdoc/cppcodeparser.cpp b/src/tools/qdoc/cppcodeparser.cpp
index 552fb6a4ba2..90f91c5f06e 100644
--- a/src/tools/qdoc/cppcodeparser.cpp
+++ b/src/tools/qdoc/cppcodeparser.cpp
@@ -870,7 +870,8 @@ const QSet<QString>& CppCodeParser::otherMetaCommands()
                            << COMMAND_QMLINSTANTIATES
                            << COMMAND_QMLDEFAULT
                            << COMMAND_QMLREADONLY
-                           << COMMAND_QMLABSTRACT;
+                           << COMMAND_QMLABSTRACT
+                           << COMMAND_ABSTRACT;
     }
     return otherMetaCommands_;
 }
@@ -1014,7 +1015,7 @@ void CppCodeParser::processOtherMetaCommand(const Doc& doc,
             }
         }
     }
-    else if (command == COMMAND_QMLABSTRACT) {
+    else if ((command == COMMAND_QMLABSTRACT) || (command == COMMAND_ABSTRACT)) {
         if (node->isQmlType() || node->isJsType())
             node->setAbstract(true);
     }
diff --git a/src/tools/qdoc/cppcodeparser.h b/src/tools/qdoc/cppcodeparser.h
index 4acd370541d..31964699a20 100644
--- a/src/tools/qdoc/cppcodeparser.h
+++ b/src/tools/qdoc/cppcodeparser.h
@@ -177,6 +177,7 @@ protected:
     QString exampleImageFilter;
 };
 
+#define COMMAND_ABSTRACT                Doc::alias("abstract")
 #define COMMAND_CLASS                   Doc::alias("class")
 #define COMMAND_CONTENTSPAGE            Doc::alias("contentspage")
 #define COMMAND_DITAMAP                 Doc::alias("ditamap")
diff --git a/src/tools/qdoc/doc.cpp b/src/tools/qdoc/doc.cpp
index bfe9cbe9357..f322bd93600 100644
--- a/src/tools/qdoc/doc.cpp
+++ b/src/tools/qdoc/doc.cpp
@@ -69,7 +69,6 @@ struct Macro
 
 enum {
     CMD_A,
-    CMD_ABSTRACT,
     CMD_ANNOTATEDLIST,
     CMD_B,
     CMD_BADCODE,
@@ -85,7 +84,6 @@ enum {
     CMD_DOTS,
     CMD_E,
     CMD_ELSE,
-    CMD_ENDABSTRACT,
     CMD_ENDCHAPTER,
     CMD_ENDCODE,
     CMD_ENDDIV,
@@ -187,7 +185,6 @@ static struct {
     QString *alias;
 } cmds[] = {
     { "a", CMD_A, 0 },
-    { "abstract", CMD_ABSTRACT, 0 },
     { "annotatedlist", CMD_ANNOTATEDLIST, 0 },
     { "b", CMD_B, 0 },
     { "badcode", CMD_BADCODE, 0 },
@@ -203,7 +200,6 @@ static struct {
     { "dots", CMD_DOTS, 0 },
     { "e", CMD_E, 0 },
     { "else", CMD_ELSE, 0 },
-    { "endabstract", CMD_ENDABSTRACT, 0 },
     { "endchapter", CMD_ENDCHAPTER, 0 },
     { "endcode", CMD_ENDCODE, 0 },
     { "enddiv", CMD_ENDDIV, 0 },
@@ -631,12 +627,6 @@ void DocParser::parse(const QString& source,
                     append(Atom::FormattingRight,ATOM_FORMATTING_PARAMETER);
                     priv->params.insert(p1);
                     break;
-                case CMD_ABSTRACT:
-                    if (openCommand(cmd)) {
-                        leavePara();
-                        append(Atom::AbstractLeft);
-                    }
-                    break;
                 case CMD_BADCODE:
                     leavePara();
                     append(Atom::CodeBad,getCode(CMD_BADCODE, marker));
@@ -748,12 +738,6 @@ void DocParser::parse(const QString& source,
                         location().warning(tr("Unexpected '\\%1'").arg(cmdName(CMD_ELSE)));
                     }
                     break;
-                case CMD_ENDABSTRACT:
-                    if (closeCommand(cmd)) {
-                        leavePara();
-                        append(Atom::AbstractRight);
-                    }
-                    break;
                 case CMD_ENDCHAPTER:
                     endSection(Doc::Chapter, cmd);
                     break;
@@ -1830,11 +1814,6 @@ bool DocParser::openCommand(int cmd)
         if (outer == CMD_LIST) {
             ok = (cmd == CMD_FOOTNOTE || cmd == CMD_LIST);
         }
-        else if (outer == CMD_ABSTRACT) {
-            ok = (cmd == CMD_LIST ||
-                  cmd == CMD_QUOTATION ||
-                  cmd == CMD_TABLE);
-        }
         else if (outer == CMD_SIDEBAR) {
             ok = (cmd == CMD_LIST ||
                   cmd == CMD_QUOTATION ||
@@ -2674,8 +2653,6 @@ void DocParser::skipToNextPreprocessorCommand()
 int DocParser::endCmdFor(int cmd)
 {
     switch (cmd) {
-    case CMD_ABSTRACT:
-        return CMD_ENDABSTRACT;
     case CMD_BADCODE:
         return CMD_ENDCODE;
     case CMD_CHAPTER:
diff --git a/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc b/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc
index 87416fcd14f..63fcee6469a 100644
--- a/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc
+++ b/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc
@@ -106,6 +106,7 @@
     \li \l {printto-command} {\\printto}
     \li \l {printuntil-command} {\\printuntil}
     \li \l {property-command} {\\property}
+    \li \l {qmlabstract-command} {\\qmlabstract}
     \li \l {qmlattachedproperty-command} {\\qmlattachedproperty}
     \li \l {qmlattachedsignal-command} {\\qmlattachedsignal}
     \li \l {qmlbasictype-command} {\\qmlbasictype}
diff --git a/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc
index 700b1a09c7e..3bf63214ad4 100644
--- a/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc
+++ b/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc
@@ -46,6 +46,7 @@
     below the \l {Topic Commands} {topic} command.
 
     \list
+      \li \l {abstract-command} {\\abstract}
       \li \l {compat-command}{\\compat},
       \li \l {contentspage-command}{\\contentspage},
       \li \l {indexpage-command}{\\indexpage},
@@ -59,6 +60,7 @@
       \li \l {overload-command}{\\overload},
       \li \l {preliminary-command}{\\preliminary},
       \li \l {previouspage-command}{\\previouspage},
+      \li \l {qmlabstract-command} {\\qmlabstract}
       \li \l {reentrant-command}{\\reentrant},
       \li \l {reimp-command}{\\reimp},
       \li \l {relates-command}{\\relates},
@@ -199,21 +201,41 @@
     index page of the collection.
 */
 
-
 /*!
     \page 16-qdoc-commands-status.html
     \previouspage Document Navigation
     \contentspage QDoc Manual
     \nextpage Thread Support
 
-    \title Reporting Status
-
-    These commands are for indicating that a documented element is
-    still under development, is becoming obsolete, is provided for
-    compatibility reasons, or is simply not to be included in the
-    public interface. The \l {since-command}{\\since} command is for
-    including information about the version when a function or class
-    first appeared.
+    \title Status
+
+    These commands are for indicating that a documented element has
+    some special status. The element could be marked as about to be
+    made obsolete, or that it is provided for compatibility with an
+    earlier version, or is simply not to be included in the public
+    interface. The \l {since-command}{\\since} command is for
+    specifying the version number in which a function or class first
+    appeared. The \l {qmlabstract-command} {\\qmlabstract} command is
+    for marking a QML type as an abstract base class.
+
+    \target abstract-command
+    \target qmlabstract-command
+    \section1 \\abstract and \\qmlabstract
+
+    \\abstract is a synonym for the \\qmlabstract command. Add this
+    command to the \l {qmltype-command} {\\qmltype} comment for a QML
+    type when that type is meant to be used \e {only} as an abstract
+    base type. When a QML type is abstract, it means that the QML type
+    that can't be instantiated. Instead, the properties in its public
+    API are included in the public properties list on the reference
+    page for each QML type that inherits the abstract QML type. The
+    properties are documented as if they are properties of the
+    inheriting QML type.
+
+    Normally, when a QML type is marked with \e{\\qmlabstract}, it is
+    also marked with \e{\\internal} so that its reference page is not
+    generated. It the abstract QML type is not marked internal, it
+    will have a reference page in the documentation.
 
     \target compat-command
     \section1 \\compat
diff --git a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
index d9b5a6f659b..9458d96045b 100644
--- a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -38,7 +38,6 @@
 
     \list
     \li \l {a-command} {\\a}
-    \li \l {abstract-command} {\\abstract}
     \li \l {annotatedlist-command} {\\annotatedlist}
     \li \l {b-command} {\\b} \span {class="newStuff"}
     \li \l {b-command} {\\bold} {(deprecated, use \\b)}
@@ -2886,19 +2885,6 @@
     parts with a special rendering, conceptual meaning or
     function.
 
-    \target abstract-command
-    \section1 \\abstract
-
-    The \\abstract and \\endabstract commands delimit a
-    document's abstract section.
-
-    The abstract section is rendered as an indented italicized
-    paragraph.
-
-    \warning The \b{\\abstract} and \b{\\endabstract} commands
-    have not been implemented. The abstract section is rendered as a
-    regular HTML paragraph.
-
     \target quotation-command
     \section1 \\quotation
 
diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp
index 3fb6acf72bc..18e538ef7b6 100644
--- a/src/tools/qdoc/htmlgenerator.cpp
+++ b/src/tools/qdoc/htmlgenerator.cpp
@@ -474,14 +474,6 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
     static bool in_para = false;
 
     switch (atom->type()) {
-    case Atom::AbstractLeft:
-        if (relative)
-            relative->doc().location().warning(tr("\abstract is not implemented."));
-        else
-            Location::information(tr("\abstract is not implemented."));
-        break;
-    case Atom::AbstractRight:
-        break;
     case Atom::AutoLink:
     case Atom::NavAutoLink:
         if (!inLink_ && !inContents_ && !inSectionHeading_) {
diff --git a/src/tools/qdoc/qmlcodeparser.cpp b/src/tools/qdoc/qmlcodeparser.cpp
index 4f5720a94d2..f485255b8ea 100644
--- a/src/tools/qdoc/qmlcodeparser.cpp
+++ b/src/tools/qdoc/qmlcodeparser.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
 #define COMMAND_SINCE                   Doc::alias("since")
 #define COMMAND_WRAPPER                 Doc::alias("wrapper")
 
+#define COMMAND_ABSTRACT                Doc::alias("abstract")
 #define COMMAND_QMLABSTRACT             Doc::alias("qmlabstract")
 #define COMMAND_QMLCLASS                Doc::alias("qmlclass")
 #define COMMAND_QMLTYPE                 Doc::alias("qmltype")
@@ -251,6 +252,7 @@ const QSet<QString>& QmlCodeParser::otherMetaCommands()
                            << COMMAND_OBSOLETE
                            << COMMAND_PRELIMINARY
                            << COMMAND_SINCE
+                           << COMMAND_ABSTRACT
                            << COMMAND_QMLABSTRACT
                            << COMMAND_INQMLMODULE
                            << COMMAND_INJSMODULE
diff --git a/src/tools/qdoc/qmlvisitor.cpp b/src/tools/qdoc/qmlvisitor.cpp
index 4803a1d63a9..360af5adf6b 100644
--- a/src/tools/qdoc/qmlvisitor.cpp
+++ b/src/tools/qdoc/qmlvisitor.cpp
@@ -55,6 +55,7 @@ QT_BEGIN_NAMESPACE
 #define COMMAND_SINCE                   Doc::alias(QLatin1String("since"))
 #define COMMAND_WRAPPER                 Doc::alias(QLatin1String("wrapper"))
 
+#define COMMAND_ABSTRACT                Doc::alias(QLatin1String("abstract"))
 #define COMMAND_QMLABSTRACT             Doc::alias(QLatin1String("qmlabstract"))
 #define COMMAND_QMLCLASS                Doc::alias(QLatin1String("qmlclass"))
 #define COMMAND_QMLTYPE                 Doc::alias(QLatin1String("qmltype"))
@@ -497,7 +498,7 @@ void QmlDocVisitor::applyMetacommands(QQmlJS::AST::SourceLocation,
         while (i != metacommands.end()) {
             QString command = *i;
             ArgList args = doc.metaCommandArgs(command);
-            if (command == COMMAND_QMLABSTRACT) {
+            if ((command == COMMAND_QMLABSTRACT) || (command == COMMAND_ABSTRACT)) {
                 if (node->isQmlType() || node->isJsType()) {
                     node->setAbstract(true);
                 }