summaryrefslogtreecommitdiffstats
path: root/src/tools
diff options
context:
space:
mode:
authorTopi Reinio <topi.reinio@digia.com>2014-07-16 14:35:00 +0200
committerTopi Reiniƶ <topi.reinio@digia.com>2014-07-18 10:14:31 +0200
commitd15309edeed53da021d058218e4c739e5903d8fd (patch)
tree7d434354aa17e533021ae5612e9b3656c02bc2a5 /src/tools
parent9c774b7621fdc99c03fad1b424b09b82057dc748 (diff)
qdoc: Support use of \value command outside \enum topic.
Even though qdoc accepts the \value command(s) anywhere in the documentation and generates tables for them, the produced output was invalid for documentation topics other than \enum. This change fixes the issue by not trying to resolve the enumeration values and removing the 'Value' column for generated tables when the \value command is used outside c++ enum documentation topic. This enables, for example, the use of the \value command for documenting acceptable values for QML enumeration properties, without having to use custom lists or tables. Task-number: QTBUG-35019 Change-Id: I597b2f9d7d03d4ab72f276752ddf53e1c405313c Reviewed-by: Jerome Pasion <jerome.pasion@digia.com> Reviewed-by: Martin Smith <martin.smith@digia.com>
Diffstat (limited to 'src/tools')
-rw-r--r--src/tools/qdoc/cppcodemarker.cpp3
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc7
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc4
-rw-r--r--src/tools/qdoc/htmlgenerator.cpp32
4 files changed, 31 insertions, 15 deletions
diff --git a/src/tools/qdoc/cppcodemarker.cpp b/src/tools/qdoc/cppcodemarker.cpp
index 60c7142229..d3cb111873 100644
--- a/src/tools/qdoc/cppcodemarker.cpp
+++ b/src/tools/qdoc/cppcodemarker.cpp
@@ -403,6 +403,9 @@ QString CppCodeMarker::markedUpFullName(const Node *node, const Node *relative)
QString CppCodeMarker::markedUpEnumValue(const QString &enumValue, const Node *relative)
{
+ if (relative->type() != Node::Enum)
+ return enumValue;
+
const Node *node = relative->parent();
QString fullName;
while (node->parent()) {
diff --git a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
index 435e243014..c04cdeca2b 100644
--- a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -2543,6 +2543,13 @@
file or namespace documentation. See the \l {enum-command}
{\\enum} documentation for an example.
+ \note Since Qt 5.4, \\value command can also be used outside the
+ \l {enum-command} {\\enum} topic. In this case, QDoc renders a
+ two-column table listing the constant name (taken as-is from the
+ first argument) and its description. This can be used, for
+ example, in \l {qmlproperty-command}{\\qmlproperty} topic for
+ documenting acceptable values for a QML enumeration property.
+
See also \l {enum-command} {\\enum} and \l {omitvalue-command} {\\omitvalue}.
\target omitvalue-command
diff --git a/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc
index b9667b7758..b50a343a22 100644
--- a/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc
+++ b/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc
@@ -1315,6 +1315,10 @@
\l {http://qt-project.org/doc/qt-4.7/qml-translate.html} {Translate}
element.
+ If the QML property is of enumeration type, or it holds a bit-wise
+ combination of flags, the \l{value-command}{\\value} command can
+ be used to document the acceptable values.
+
\target qmlsignal-command
\section1 \\qmlsignal
diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp
index 46c90205fe..7a19e3c027 100644
--- a/src/tools/qdoc/htmlgenerator.cpp
+++ b/src/tools/qdoc/htmlgenerator.cpp
@@ -854,21 +854,24 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
out() << "<dl>\n";
}
else if (atom->string() == ATOM_LIST_VALUE) {
+ out() << "<table class=\"valuelist\">";
threeColumnEnumValueTable_ = isThreeColumnEnumValueTable(atom);
if (threeColumnEnumValueTable_) {
- out() << "<table class=\"valuelist\">";
if (++numTableRows_ % 2 == 1)
out() << "<tr valign=\"top\" class=\"odd\">";
else
out() << "<tr valign=\"top\" class=\"even\">";
- out() << "<th class=\"tblConst\">Constant</th>"
- << "<th class=\"tblval\">Value</th>"
- << "<th class=\"tbldscr\">Description</th></tr>\n";
+ out() << "<th class=\"tblConst\">Constant</th>";
+
+ // If not in \enum topic, skip the value column
+ if (relative->type() == Node::Enum)
+ out() << "<th class=\"tblval\">Value</th>";
+
+ out() << "<th class=\"tbldscr\">Description</th></tr>\n";
}
else {
- out() << "<table class=\"valuelist\">"
- << "<tr><th class=\"tblConst\">Constant</th><th class=\"tblVal\">Value</th></tr>\n";
+ out() << "<tr><th class=\"tblConst\">Constant</th><th class=\"tblVal\">Value</th></tr>\n";
}
}
else {
@@ -903,19 +906,18 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
// ### Trenton
QString t= protectEnc(plainCode(marker->markedUpEnumValue(atom->next()->string(),relative)));
- out() << "<tr><td class=\"topAlign\"><tt>" << t << "</tt></td><td class=\"topAlign\">";
+ out() << "<tr><td class=\"topAlign\"><tt>" << t << "</tt>";
- QString itemValue;
if (relative->type() == Node::Enum) {
+ out() << "</td><td class=\"topAlign\">";
const EnumNode *enume = static_cast<const EnumNode *>(relative);
- itemValue = enume->itemValue(atom->next()->string());
- }
-
- if (itemValue.isEmpty())
- out() << '?';
- else
- out() << "<tt>" << protectEnc(itemValue) << "</tt>";
+ QString itemValue = enume->itemValue(atom->next()->string());
+ if (itemValue.isEmpty())
+ out() << '?';
+ else
+ out() << "<tt>" << protectEnc(itemValue) << "</tt>";
+ }
skipAhead = 1;
}
break;