From 0d43b8c617c4bb564e0789994de94f26506ad30b Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Tue, 13 Mar 2012 14:46:28 +0100 Subject: [PATCH] qdoc3: qdoc now handles overloaded methods for QML When a C++ class is documented as a QML type, it can have overloaded QML methods. These are now handled correctly by qdoc. The method list for QML types is now output with the full method signature. For signals and handlers too. Task-number: QTBUG-24670 Change-Id: If529d4136f5b480373b6ac25d2dceef15e6ea3db Reviewed-by: Casper van Donderen --- src/tools/qdoc/codemarker.cpp | 16 ++++++++++++++-- src/tools/qdoc/cppcodemarker.cpp | 36 ++++++++++++++++++++++++++++++++---- src/tools/qdoc/cppcodeparser.cpp | 3 ++- src/tools/qdoc/ditaxmlgenerator.cpp | 26 +++++++++++++++++++++----- src/tools/qdoc/ditaxmlgenerator.h | 2 +- src/tools/qdoc/node.cpp | 1 + src/tools/qdoc/node.h | 9 +++++++-- src/tools/qdoc/tree.cpp | 3 +++ 8 files changed, 81 insertions(+), 15 deletions(-) diff --git a/src/tools/qdoc/codemarker.cpp b/src/tools/qdoc/codemarker.cpp index 791e080..9f22a28 100644 --- a/src/tools/qdoc/codemarker.cpp +++ b/src/tools/qdoc/codemarker.cpp @@ -288,12 +288,17 @@ QString CodeMarker::taggedNode(const Node* node) } tag = QLatin1String("@property"); break; + case Node::QmlMethod: + case Node::QmlSignal: + case Node::QmlSignalHandler: + tag = QLatin1String("@function"); + break; default: tag = QLatin1String("@unknown"); break; } - return QLatin1Char('<') + tag + QLatin1Char('>') + protect(name) - + QLatin1String("'); + return (QLatin1Char('<') + tag + QLatin1Char('>') + protect(name) + + QLatin1String("')); } QString CodeMarker::taggedQmlNode(const Node* node) @@ -373,6 +378,13 @@ QString CodeMarker::sortName(const Node *node, const QString* name) if (node->type() == Node::Property || node->type() == Node::Variable) return QLatin1Char('E') + nodeName; + if ((node->type() == Node::QmlMethod) || + (node->type() == Node::QmlSignal) || + (node->type() == Node::QmlSignalHandler)) { + const FunctionNode* func = static_cast(node); + return QLatin1String("E") + func->signature(); + } + return QLatin1Char('B') + nodeName; } diff --git a/src/tools/qdoc/cppcodemarker.cpp b/src/tools/qdoc/cppcodemarker.cpp index cc68865..3e7d190 100644 --- a/src/tools/qdoc/cppcodemarker.cpp +++ b/src/tools/qdoc/cppcodemarker.cpp @@ -342,19 +342,47 @@ QString CppCodeMarker::markedUpSynopsis(const Node *node, QString CppCodeMarker::markedUpQmlItem(const Node* node, bool summary) { QString name = taggedQmlNode(node); - if (summary) { + if (summary) name = linkTag(node,name); - } else if (node->type() == Node::QmlProperty) { + else if (node->type() == Node::QmlProperty) { const QmlPropertyNode* pn = static_cast(node); if (pn->isAttached()) name.prepend(pn->element() + QLatin1Char('.')); } name = "<@name>" + name + ""; - QString synopsis = name; + QString synopsis; if (node->type() == Node::QmlProperty) { const QmlPropertyNode* pn = static_cast(node); - synopsis += " : " + typified(pn->dataType()); + synopsis = name + " : " + typified(pn->dataType()); } + else if ((node->type() == Node::QmlMethod) || + (node->type() == Node::QmlSignal) || + (node->type() == Node::QmlSignalHandler)) { + const FunctionNode* func = static_cast(node); + if (!func->returnType().isEmpty()) + synopsis = typified(func->returnType()) + QLatin1Char(' ') + name; + else + synopsis = name; + synopsis += "("; + if (!func->parameters().isEmpty()) { + QList::ConstIterator p = func->parameters().begin(); + while (p != func->parameters().end()) { + if (p != func->parameters().begin()) + synopsis += ", "; + synopsis += typified((*p).leftType()); + if (!(*p).name().isEmpty()) { + if (!synopsis.endsWith("(")) + synopsis += " "; + synopsis += "<@param>" + protect((*p).name()) + ""; + } + synopsis += protect((*p).rightType()); + ++p; + } + } + synopsis += QLatin1Char(')'); + } + else + synopsis = name; QString extra; if (summary) { diff --git a/src/tools/qdoc/cppcodeparser.cpp b/src/tools/qdoc/cppcodeparser.cpp index b83e617..a7cdeea 100644 --- a/src/tools/qdoc/cppcodeparser.cpp +++ b/src/tools/qdoc/cppcodeparser.cpp @@ -797,8 +797,9 @@ Node* CppCodeParser::processTopicCommand(const Doc& doc, return makeFunctionNode(doc,arg,qmlClass,Node::QmlSignal,false,COMMAND_QMLSIGNAL); else if (command == COMMAND_QMLATTACHEDSIGNAL) return makeFunctionNode(doc,arg,qmlClass,Node::QmlSignal,true,COMMAND_QMLATTACHEDSIGNAL); - else if (command == COMMAND_QMLMETHOD) + else if (command == COMMAND_QMLMETHOD) { return makeFunctionNode(doc,arg,qmlClass,Node::QmlMethod,false,COMMAND_QMLMETHOD); + } else if (command == COMMAND_QMLATTACHEDMETHOD) return makeFunctionNode(doc,arg,qmlClass,Node::QmlMethod,true,COMMAND_QMLATTACHEDMETHOD); else diff --git a/src/tools/qdoc/ditaxmlgenerator.cpp b/src/tools/qdoc/ditaxmlgenerator.cpp index a4c5cbe..aaf5db1 100644 --- a/src/tools/qdoc/ditaxmlgenerator.cpp +++ b/src/tools/qdoc/ditaxmlgenerator.cpp @@ -297,14 +297,23 @@ void DitaXmlGenerator::writeStartTag(DitaTag t) /*! Pop the current DITA tag off the stack, and write the - appropriate end tag to the DITA XML file. + appropriate end tag to the DITA XML file. If \a t is + not \e DT_NONE (default), then \a t contains the enum + value of the tag that should be on top of the stack. + + If the stack is empty, no end tag is written and false + is returned. Otherwise, an end tag is written and true + is returned. */ -void DitaXmlGenerator::writeEndTag(DitaTag t) +bool DitaXmlGenerator::writeEndTag(DitaTag t) { + if (tagStack.isEmpty()) + return false; DitaTag top = tagStack.pop(); if (t > DT_NONE && top != t) qDebug() << "Expected:" << t << "ACTUAL:" << top; xmlWriter().writeEndElement(); + return true; } /*! @@ -2316,7 +2325,10 @@ void DitaXmlGenerator::generateFakeNode(const FakeNode* fake, CodeMarker* marker } } leaveSection(); // - writeEndTag(); // + if (!writeEndTag()) { // + fake->doc().location().warning(tr("Pop of empty XML tag stack; generating DITA for '%1'").arg(fake->name())); + return; + } writeRelatedLinks(fake, marker); writeEndTag(); // } @@ -3215,16 +3227,19 @@ void DitaXmlGenerator::generateQmlItem(const Node* node, } marked.replace(QRegExp("<@param>([a-z]+)_([1-9n])"), "\\1\\2"); +#if 0 marked.replace("<@param>", ""); marked.replace("", ""); marked.replace("<@extra>", ""); marked.replace("", ""); - +#endif if (summary) { marked.remove("<@type>"); marked.remove(""); } + if (marked.contains("setAudioAlertEnabled")) + qDebug() << "MARKED:" << marked; writeText(marked, marker, relative); } @@ -3572,7 +3587,8 @@ void DitaXmlGenerator::writeText(const QString& markedCode, html.clear(); } writeStartTag(DT_i); - writeCharacters(" " + arg.toString()); + //writeCharacters(" " + arg.toString()); + writeCharacters(arg.toString()); writeEndTag(); // } else if (k == 5) { // <@extra> diff --git a/src/tools/qdoc/ditaxmlgenerator.h b/src/tools/qdoc/ditaxmlgenerator.h index ba96265..bc3ed93 100644 --- a/src/tools/qdoc/ditaxmlgenerator.h +++ b/src/tools/qdoc/ditaxmlgenerator.h @@ -445,7 +445,7 @@ private: void writeDitaMap(const Tree* tree); void writeDitaMap(const DitaMapNode* node); void writeStartTag(DitaTag t); - void writeEndTag(DitaTag t=DT_NONE); + bool writeEndTag(DitaTag t=DT_NONE); DitaTag currentTag(); void clearSectionNesting() { sectionNestingLevel = 0; } int enterApiDesc(const QString& outputclass, const QString& title); diff --git a/src/tools/qdoc/node.cpp b/src/tools/qdoc/node.cpp index 13c51c7..0575bfb 100644 --- a/src/tools/qdoc/node.cpp +++ b/src/tools/qdoc/node.cpp @@ -98,6 +98,7 @@ Node::Node(Type type, InnerNode *parent, const QString& name) safeness_(UnspecifiedSafeness), pageType_(NoPageType), status_(Commendable), + indexNodeFlag_(false), parent_(parent), relatesTo_(0), name_(name) diff --git a/src/tools/qdoc/node.h b/src/tools/qdoc/node.h index 440b22d..23ee38c 100644 --- a/src/tools/qdoc/node.h +++ b/src/tools/qdoc/node.h @@ -173,6 +173,7 @@ public: void setPageType(PageType t) { pageType_ = t; } void setPageType(const QString& t); void setParent(InnerNode* n) { parent_ = n; } + void setIndexNodeFlag() { indexNodeFlag_ = true; } virtual bool isInnerNode() const = 0; virtual bool isReimp() const { return false; } @@ -183,6 +184,7 @@ public: virtual bool isAbstract() const { return false; } virtual void setAbstract(bool ) { } virtual QString title() const { return QString(); } + bool isIndexNode() const { return indexNodeFlag_; } Type type() const { return nodeType_; } virtual SubType subType() const { return NoSubType; } InnerNode* parent() const { return parent_; } @@ -240,13 +242,16 @@ protected: private: -#ifdef Q_WS_WIN Type nodeType_; Access access_; ThreadSafeness safeness_; PageType pageType_; Status status_; -#else + bool indexNodeFlag_; + +#if 0 + //ifdef Q_WS_WIN + //else Type nodeType_ : 4; Access access_ : 2; ThreadSafeness safeness_ : 2; diff --git a/src/tools/qdoc/tree.cpp b/src/tools/qdoc/tree.cpp index c52e457..4b2a8ba 100644 --- a/src/tools/qdoc/tree.cpp +++ b/src/tools/qdoc/tree.cpp @@ -1050,6 +1050,8 @@ void Tree::readIndexFile(const QString& path) } /*! + Read a
element from the index file and create the + appropriate node(s). */ void Tree::readIndexSection(const QDomElement& element, InnerNode* parent, @@ -1364,6 +1366,7 @@ void Tree::readIndexSection(const QDomElement& element, Doc doc(location, location, " ", emptySet); // placeholder section->setDoc(doc); + section->setIndexNodeFlag(); if (section->isInnerNode()) { InnerNode* inner = static_cast(section); -- 2.7.4