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

qdoc: Support use of \value command outside \enum topic.

Browse Source 
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>
This commit is contained in:
Topi Reinio 2014-07-16 14:35:00 +02:00 committed by Topi Reiniö
parent 9c774b7621
commit d15309edee
4 changed files with 31 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

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

4
src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc
View File

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

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

@ -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());
QString itemValue = enume->itemValue(atom->next()->string());
if (itemValue.isEmpty())
out() << '?';
else
out() << "<tt>" << protectEnc(itemValue) << "</tt>";
}
if (itemValue.isEmpty())
out() << '?';
else
out() << "<tt>" << protectEnc(itemValue) << "</tt>";
skipAhead = 1;
}
break;