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 <venugopal.shivashankar@digia.com>
Reviewed-by: Martin Smith <martin.smith@digia.com>

11 files changed, 40 insertions, 63 deletions

diff --git a/src/tools/qdoc/atom.cpp b/src/tools/qdoc/atom.cpp
index ebbe685985..f50f401c5b 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 dae106a742..86b8ba7b3c 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 552fb6a4ba..90f91c5f06 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 4acd370541..31964699a2 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 bfe9cbe935..f322bd9360 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 87416fcd14..63fcee6469 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 700b1a09c7..3bf63214ad 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 d9b5a6f659..9458d96045 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 3fb6acf72b..18e538ef7b 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 4f5720a94d..f485255b8e 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 4803a1d63a..360af5adf6 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);
                 }