whytofly
/
qt6-bb10
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

qdoc: Make \target and \keyword commands link as expected 

When resolving targets added for each node, QDoc didn't run the
check recursively; this meant that \target and \keyword commands
did not link when used in documentation nodes that are not direct
children of the root node. There include e.g. documentation for
functions and QML properties/methods.

This commit fixes that issue, and also modifies the behavior of
\keyword slightly: Using a \keyword no longer generates a HTML
anchor reference. Instead, linking to a keyword links directly
to the parent item which defines the \keyword. This produces
cleaner HTML by omitting unnecessary anchors.

Change-Id: I87659642770a5372409ecb09cb576fbad295155e
Task-number: QTBUG-47286
Reviewed-by: Martin Smith <martin.smith@digia.com>
bb10
Topi Reinio 2015-07-30 12:51:22 +02:00 committed by Topi Reiniö
parent 789c9954c7
commit 7b77ef6b0a
5 changed files with 23 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -2092,8 +2092,11 @@
{sa-command} {\\sa (see also)} commands.
The \\keyword command is like the \l {target-command} {\\target}
command, but stronger. A keyword can be linked from anywhere using
a simple syntax.
command, except when linking to keyword the link goes to the top of
the QDoc comment where the \\keyword appears in. If you want to
create a link target to a \c section unit within a \\page, use
\\target instead. A keyword can be linked from anywhere using a
simple syntax.
Keywords must be unique over all the documents processed during
the QDoc run. The command uses the rest of the line as its

9
src/tools/qdoc/helpprojectwriter.cpp
View File

@ -307,8 +307,7 @@ bool HelpProjectWriter::generateSection(HelpProject &project,
QStringList details;
details << keyword->string()
<< keyword->string()
<< gen_->fullDocumentLocation(node, false) +
QLatin1Char('#') + Doc::canonicalTitle(keyword->string());
<< gen_->fullDocumentLocation(node, false);
project.keywords.append(details);
}
else
@ -357,8 +356,7 @@ bool HelpProjectWriter::generateSection(HelpProject &project,
QStringList details;
details << keyword->string()
<< keyword->string()
<< gen_->fullDocumentLocation(node, false) +
QLatin1Char('#') + Doc::canonicalTitle(keyword->string());
<< gen_->fullDocumentLocation(node, false);
project.keywords.append(details);
}
else
@ -438,8 +436,7 @@ bool HelpProjectWriter::generateSection(HelpProject &project,
QStringList details;
details << keyword->string()
<< keyword->string()
<< gen_->fullDocumentLocation(node, false) +
QLatin1Char('#') + Doc::canonicalTitle(keyword->string());
<< gen_->fullDocumentLocation(node, false);
project.keywords.append(details);
} else
docNode->doc().location().warning(

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

@ -283,12 +283,17 @@ QString HtmlGenerator::format()
*/
void HtmlGenerator::generateKeywordAnchors(const Node* node)
{
Q_UNUSED(node);
// Disabled: keywords always link to the top of the QDoc
// comment they appear in, and do not use a dedicated anchor.
#if 0
if (!node->doc().isEmpty()) {
const QList<Atom*>& keywords = node->doc().keywords();
foreach (Atom* a, keywords) {
out() << QLatin1String("<a name=\"") << Doc::canonicalTitle(a->string()) << QLatin1String("\"></a>");
}
}
#endif
}
/*!
@ -3809,10 +3814,8 @@ QString HtmlGenerator::getAutoLink(const Atom *atom, const Node *relative, const
link = linkForNode(*node, relative);
if ((*node)->docSubtype() == Node::Image)
link = "images/used-in-examples/" + link;
if (!ref.isEmpty())
link += QLatin1Char('#') + ref;
}
else if (!ref.isEmpty()) {
if (!ref.isEmpty()) {
int hashtag = link.lastIndexOf(QChar('#'));
if (hashtag != -1)
link.truncate(hashtag);

6
src/tools/qdoc/tree.cpp
View File

@ -995,7 +995,6 @@ void Tree::insertTarget(const QString& name,
*/
void Tree::resolveTargets(Aggregate* root)
{
// need recursion
foreach (Node* child, root->childNodes()) {
if (child->type() == Node::Document) {
DocumentNode* node = static_cast<DocumentNode*>(child);
@ -1039,9 +1038,8 @@ void Tree::resolveTargets(Aggregate* root)
QString ref = refForAtom(keywords.at(i));
QString title = keywords.at(i)->string();
if (!ref.isEmpty() && !title.isEmpty()) {
QString key = Doc::canonicalTitle(title);
TargetRec* target = new TargetRec(ref, title, TargetRec::Keyword, child, 1);
nodesByTargetRef_.insert(key, target);
nodesByTargetRef_.insert(Doc::canonicalTitle(title), target);
nodesByTargetTitle_.insert(title, target);
}
}
@ -1059,6 +1057,8 @@ void Tree::resolveTargets(Aggregate* root)
}
}
}
if (child->isAggregate())
resolveTargets(static_cast<Aggregate*>(child));
}
}

7
src/tools/qdoc/tree.h
View File

@ -56,7 +56,12 @@ struct TargetRec
TargetRec::TargetType type,
Node* node,
int priority)
: node_(node), ref_(name), title_(title), priority_(priority), type_(type) { }
: node_(node), ref_(name), title_(title), priority_(priority), type_(type) {
// Discard the dedicated ref for keywords - they always
// link to the top of the QDoc comment they appear in
if (type == Keyword)
ref_.clear();
}
bool isEmpty() const { return ref_.isEmpty(); }