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]>
brad0 · May 12, 2015 · 5891f90 · 5891f90
1 parent ada8f19
commit 5891f90
Show file tree

Hide file tree

Showing 11 changed files with 40 additions and 63 deletions.
diff --git 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
@@ -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
@@ -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
@@ -177,6 +177,7 @@ class CppCodeParser : public CodeParser
     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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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);
                 }