summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMartin Smith <martin.smith@digia.com>2014-10-30 15:22:17 +0100
committerMartin Smith <martin.smith@digia.com>2014-11-12 08:11:04 +0100
commit1936e4973f6309ece1b83a886c6c6d9211e2155e (patch)
tree550827c552fe93037426073519bc312fdc638a39
parent8bed6b6a7ffd3961f3da726d551f5e2563d95965 (diff)
qdoc: Generate \keyword anchors at the top of the page
Currently, qdoc processes \keyword and \target the same way. The negative effect of this is that when either command appears at the top of a qdoc comment, the anchor it generates in the html file is just above the details section on the html page. This is usually wrong, especially for \keyword commands, where the anchor generated should always be at the top of the page/text where the \keyword appears. This update implements that. \target anchors are meant to be used when the anchor should appear somewhere in the middle of the page/text, exactly where the \target command appears. Change-Id: Ibbbf1087562a977ff74ccd98febfe9310ecba8f0 Task-number: QTBUG-42290 Reviewed-by: Topi Reiniö <topi.reinio@digia.com>
Diffstat
-rw-r--r--src/tools/qdoc/atom.cpp4
-rw-r--r--src/tools/qdoc/atom.h1
-rw-r--r--src/tools/qdoc/doc.cpp9
-rw-r--r--src/tools/qdoc/htmlgenerator.cpp24
-rw-r--r--src/tools/qdoc/htmlgenerator.h1
-rw-r--r--src/tools/qdoc/tree.cpp2
6 files changed, 37 insertions, 4 deletions
diff --git a/src/tools/qdoc/atom.cpp b/src/tools/qdoc/atom.cpp
index e227526d90c..9aaa1af3198 100644
--- a/src/tools/qdoc/atom.cpp
+++ b/src/tools/qdoc/atom.cpp
@@ -97,6 +97,9 @@ QT_BEGIN_NAMESPACE
\value ImageText
\value ImportantNote
\value InlineImage
+ \value JavaScript
+ \value EndJavaScript
+ \value Keyword
\value LineBreak
\value Link
\value LinkNode
@@ -183,6 +186,7 @@ static const struct {
{ "InlineImage", Atom::InlineImage },
{ "JavaScript", Atom::JavaScript },
{ "EndJavaScript", Atom::EndJavaScript },
+ { "Keyword", Atom::Keyword },
{ "LegaleseLeft", Atom::LegaleseLeft },
{ "LegaleseRight", Atom::LegaleseRight },
{ "LineBreak", Atom::LineBreak },
diff --git a/src/tools/qdoc/atom.h b/src/tools/qdoc/atom.h
index daa94a1fb88..2eb34a042b0 100644
--- a/src/tools/qdoc/atom.h
+++ b/src/tools/qdoc/atom.h
@@ -84,6 +84,7 @@ public:
InlineImage,
JavaScript,
EndJavaScript,
+ Keyword,
LegaleseLeft,
LegaleseRight,
LineBreak,
diff --git a/src/tools/qdoc/doc.cpp b/src/tools/qdoc/doc.cpp
index 53d8ea885df..ce77caec9c4 100644
--- a/src/tools/qdoc/doc.cpp
+++ b/src/tools/qdoc/doc.cpp
@@ -1690,12 +1690,15 @@ void DocParser::insertTarget(const QString &target, bool keyword)
}
else {
targetMap_.insert(target, location());
- append(Atom::Target, target);
priv->constructExtra();
- if (keyword)
+ if (keyword) {
+ append(Atom::Keyword, target);
priv->extra->keywords_.append(priv->text.lastAtom());
- else
+ }
+ else {
+ append(Atom::Target, target);
priv->extra->targets_.append(priv->text.lastAtom());
+ }
}
}
diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp
index f08f84abaed..a3e8dac1e8b 100644
--- a/src/tools/qdoc/htmlgenerator.cpp
+++ b/src/tools/qdoc/htmlgenerator.cpp
@@ -271,6 +271,20 @@ QString HtmlGenerator::format()
}
/*!
+ Generate targets for any \keyword commands that were seen
+ in the qdoc comment for the \a node.
+ */
+void HtmlGenerator::generateKeywordAnchors(const Node* node)
+{
+ if (!node->doc().isEmpty()) {
+ const QList<Atom*>& keywords = node->doc().keywords();
+ foreach (Atom* a, keywords) {
+ out() << "<a name=\"" << Doc::canonicalTitle(a->string()) << "\"></a>";
+ }
+ }
+}
+
+/*!
Traverses the current tree generating all the HTML documentation.
*/
void HtmlGenerator::generateDocs()
@@ -1229,6 +1243,8 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
break;
case Atom::TableOfContents:
break;
+ case Atom::Keyword:
+ break;
case Atom::Target:
out() << "<a name=\"" << Doc::canonicalTitle(atom->string()) << "\"></a>";
break;
@@ -1276,8 +1292,10 @@ void HtmlGenerator::generateClassLikeNode(InnerNode* inner, CodeMarker* marker)
subtitleText << "(" << Atom(Atom::AutoLink, fullTitle) << ")" << Atom(Atom::LineBreak);
generateHeader(title, inner, marker);
+
sections = marker->sections(inner, CodeMarker::Summary, CodeMarker::Okay);
generateTableOfContents(inner,marker,&sections);
+ generateKeywordAnchors(inner);
generateTitle(title, subtitleText, SmallSubTitle, inner, marker);
generateBrief(inner, marker);
generateRequisites(inner, marker);
@@ -1450,6 +1468,7 @@ void HtmlGenerator::generateQmlTypePage(QmlClassNode* qcn, CodeMarker* marker)
QList<Section> sections = marker->qmlSections(qcn, CodeMarker::Summary);
generateTableOfContents(qcn, marker, &sections);
marker = CodeMarker::markerForLanguage(QLatin1String("QML"));
+ generateKeywordAnchors(qcn);
generateTitle(htmlTitle, Text() << qcn->subTitle(), subTitleSize, qcn, marker);
generateBrief(qcn, marker);
generateQmlRequisites(qcn, marker);
@@ -1521,6 +1540,7 @@ void HtmlGenerator::generateQmlBasicTypePage(QmlBasicTypeNode* qbtn, CodeMarker*
generateHeader(htmlTitle, qbtn, marker);
QList<Section> sections = marker->sections(qbtn, CodeMarker::Summary, CodeMarker::Okay);
generateTableOfContents(qbtn,marker,&sections);
+ generateKeywordAnchors(qbtn);
generateTitle(htmlTitle,
Text() << qbtn->subTitle(),
subTitleSize,
@@ -1567,6 +1587,7 @@ void HtmlGenerator::generateDocNode(DocNode* dn, CodeMarker* marker)
(dn->name() != QString("qtexamplesandtutorials.html")))
generateTableOfContents(dn,marker,0);
+ generateKeywordAnchors(dn);
generateTitle(fullTitle,
Text() << dn->subTitle(),
subTitleSize,
@@ -1651,6 +1672,7 @@ void HtmlGenerator::generateCollectionNode(CollectionNode* cn, CodeMarker* marke
generateHeader(fullTitle, cn, marker);
generateTableOfContents(cn,marker,0);
+ generateKeywordAnchors(cn);
generateTitle(fullTitle, Text() << cn->subTitle(), subTitleSize, cn, marker);
if (cn->isModule()) {
@@ -3901,6 +3923,7 @@ void HtmlGenerator::generateDetailedMember(const Node *node,
generateMacRef(node, marker);
#endif
generateExtractionMark(node, MemberMark);
+ generateKeywordAnchors(node);
QString nodeRef = refForNode(node);
if (node->type() == Node::Enum
&& (enume = static_cast<const EnumNode *>(node))->flagsType()) {
@@ -4137,6 +4160,7 @@ void HtmlGenerator::generateDetailedQmlMember(Node *node,
generateMacRef(node, marker);
#endif
generateExtractionMark(node, MemberMark);
+ generateKeywordAnchors(node);
out() << "<div class=\"qmlitem\">";
QString nodeRef = refForNode(node);
if (node->type() == Node::QmlPropertyGroup) {
diff --git a/src/tools/qdoc/htmlgenerator.h b/src/tools/qdoc/htmlgenerator.h
index b8ead2bbec2..22e6aa68ddc 100644
--- a/src/tools/qdoc/htmlgenerator.h
+++ b/src/tools/qdoc/htmlgenerator.h
@@ -105,6 +105,7 @@ protected:
void generateManifestFile(QString manifest, QString element);
void readManifestMetaContent(const Config &config);
+ void generateKeywordAnchors(const Node* node);
private:
enum SubTitleSize { SmallSubTitle, LargeSubTitle };
diff --git a/src/tools/qdoc/tree.cpp b/src/tools/qdoc/tree.cpp
index 6610bd0db4d..819951d0e05 100644
--- a/src/tools/qdoc/tree.cpp
+++ b/src/tools/qdoc/tree.cpp
@@ -1135,7 +1135,7 @@ QString Tree::refForAtom(const Atom* atom)
if (atom) {
if (atom->type() == Atom::SectionLeft)
return Doc::canonicalTitle(Text::sectionHeading(atom).toString());
- if (atom->type() == Atom::Target)
+ if ((atom->type() == Atom::Target) || (atom->type() == Atom::Keyword))
return Doc::canonicalTitle(atom->string());
}
return QString();
generated by cgit v1.2.3 (git 2.25.1) at 2025-12-16 06:27:52 +0000