AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

qdoc: Update documentation of \qmlabstract

Browse Source 
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>
This commit is contained in:
Martin Smith 2015-05-08 10:03:23 +02:00
parent ada8f1985d
commit 5891f90846
11 changed files with 39 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/tools/qdoc/atom.cpp
View File

@ -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 },

2
src/tools/qdoc/atom.h
View File

@ -47,8 +47,6 @@ class Atom
{
public:
enum AtomType {
AbstractLeft,
AbstractRight,
AnnotatedList,
AutoLink,
BaseName,

5
src/tools/qdoc/cppcodeparser.cpp
View File

@ -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);
}

1
src/tools/qdoc/cppcodeparser.h
View File

@ -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")

23
src/tools/qdoc/doc.cpp
View File

@ -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:

1
src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc
View File

@ -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}

38
src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc
View File

@ -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
\title 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.
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

14
src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
View File

@ -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

8
src/tools/qdoc/htmlgenerator.cpp
View File

@ -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_) {

2
src/tools/qdoc/qmlcodeparser.cpp
View File

@ -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

3
src/tools/qdoc/qmlvisitor.cpp
View File

@ -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);
}