From aea74dcaee2d6930e4d69cbda83088703b45816e Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Tue, 14 Apr 2015 11:27:59 +0200 Subject: qdoc: Properly document "private" signals MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When a signal declaration is marked with QSignalPrivate, This note is included in its documentation: "Note: This is a private signal. It must not be emitted by the user." For Notifier signals, [see note] is appended to the signature line, and the Note is printed below the list. Change-Id: Ie792894ace56cda47fd9a45af9c732f408ac45f6 Task-number: QTBUG-45535 Reviewed-by: Topi Reiniö --- src/tools/qdoc/cppcodeparser.cpp | 5 +++++ src/tools/qdoc/generator.cpp | 17 +++++++++++++++++ src/tools/qdoc/generator.h | 1 + src/tools/qdoc/htmlgenerator.cpp | 17 +++++++++++++++++ src/tools/qdoc/node.cpp | 2 ++ src/tools/qdoc/node.h | 3 +++ src/tools/qdoc/tokenizer.cpp | 3 ++- src/tools/qdoc/tokenizer.h | 4 ++-- 8 files changed, 49 insertions(+), 3 deletions(-) (limited to 'src/tools/qdoc') diff --git a/src/tools/qdoc/cppcodeparser.cpp b/src/tools/qdoc/cppcodeparser.cpp index 4fbe20b09e..f12fb70227 100644 --- a/src/tools/qdoc/cppcodeparser.cpp +++ b/src/tools/qdoc/cppcodeparser.cpp @@ -1329,6 +1329,11 @@ bool CppCodeParser::matchParameter(FunctionNode *func) QString name; CodeChunk defaultValue; + if (match(Tok_QPrivateSignal)) { + func->setPrivateSignal(); + return true; + } + if (!matchDataType(&dataType, &name)) { return false; } diff --git a/src/tools/qdoc/generator.cpp b/src/tools/qdoc/generator.cpp index 55050806ec..2ff4df9bd7 100644 --- a/src/tools/qdoc/generator.cpp +++ b/src/tools/qdoc/generator.cpp @@ -1249,6 +1249,23 @@ void Generator::generateStatus(const Node *node, CodeMarker *marker) generateText(text, node, marker); } +/*! + Generates a bold line that says: + "The signal is private, not emitted by the user. + The function is public so the user can pass it to connect()." + */ +void Generator::generatePrivateSignalNote(const Node* node, CodeMarker* marker) +{ + Text text; + text << Atom::ParaLeft + << Atom(Atom::FormattingLeft, ATOM_FORMATTING_BOLD) + << "Note: " + << Atom(Atom::FormattingRight, ATOM_FORMATTING_BOLD) + << "This is a private signal. It can be used in signal connections but cannot be emitted by the user." + << Atom::ParaRight; + generateText(text, node, marker); +} + /*! Generate the documentation for \a relative. i.e. \a relative is the node that reporesentas the entity where a qdoc comment diff --git a/src/tools/qdoc/generator.h b/src/tools/qdoc/generator.h index 3165e8d449..6d0de8df44 100644 --- a/src/tools/qdoc/generator.h +++ b/src/tools/qdoc/generator.h @@ -156,6 +156,7 @@ protected: const QString& tag); void generateSince(const Node *node, CodeMarker *marker); void generateStatus(const Node *node, CodeMarker *marker); + void generatePrivateSignalNote(const Node* node, CodeMarker* marker); void generateThreadSafeness(const Node *node, CodeMarker *marker); QString getMetadataElement(const InnerNode* inner, const QString& t); QStringList getMetadataElements(const InnerNode* inner, const QString& t); diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp index f315099f18..f0a23ac65e 100644 --- a/src/tools/qdoc/htmlgenerator.cpp +++ b/src/tools/qdoc/htmlgenerator.cpp @@ -3265,6 +3265,7 @@ void HtmlGenerator::generateSectionList(const Section& section, { bool alignNames = true; if (!section.members.isEmpty()) { + bool hasPrivateSignals = false; bool twoColumn = false; if (style == CodeMarker::Subpage) { alignNames = false; @@ -3307,6 +3308,14 @@ void HtmlGenerator::generateSectionList(const Section& section, prefix = prefix.left(section.keys.at(i).indexOf("::")+1); } generateSynopsis(*m, relative, marker, style, alignNames, &prefix); + if ((*m)->isFunction()) { + const FunctionNode* fn = static_cast(*m); + if (fn->isPrivateSignal()) { + hasPrivateSignals = true; + if (alignNames) + out() << "[see note below]"; + } + } if (alignNames) out() << "\n"; else @@ -3321,6 +3330,9 @@ void HtmlGenerator::generateSectionList(const Section& section, if (twoColumn) out() << "\n\n"; } + if (hasPrivateSignals && alignNames) { + generatePrivateSignalNote(relative, marker); + } } if (style == CodeMarker::Summary && !section.inherited.isEmpty()) { @@ -4023,6 +4035,11 @@ void HtmlGenerator::generateDetailedMember(const Node *node, generateSectionList(notifiers, node, marker, CodeMarker::Accessors); } } + else if (node->isFunction()) { + const FunctionNode* fn = static_cast(node); + if (fn->isPrivateSignal()) + generatePrivateSignalNote(node, marker); + } else if (node->type() == Node::Enum) { const EnumNode *enume = static_cast(node); if (enume->flagsType()) { diff --git a/src/tools/qdoc/node.cpp b/src/tools/qdoc/node.cpp index 24c64538c3..230ce50df8 100644 --- a/src/tools/qdoc/node.cpp +++ b/src/tools/qdoc/node.cpp @@ -1804,6 +1804,7 @@ FunctionNode::FunctionNode(InnerNode *parent, const QString& name) ove(false), reimp(false), attached_(false), + privateSignal_(false), rf(0), ap(0) { @@ -1824,6 +1825,7 @@ FunctionNode::FunctionNode(Type type, InnerNode *parent, const QString& name, bo ove(false), reimp(false), attached_(attached), + privateSignal_(false), rf(0), ap(0) { diff --git a/src/tools/qdoc/node.h b/src/tools/qdoc/node.h index fc9d33edc2..85e724b9ca 100644 --- a/src/tools/qdoc/node.h +++ b/src/tools/qdoc/node.h @@ -928,6 +928,8 @@ public: virtual QString logicalModuleIdentifier() const Q_DECL_OVERRIDE { return parent()->logicalModuleIdentifier(); } + bool isPrivateSignal() const { return privateSignal_; } + void setPrivateSignal() { privateSignal_ = true; } void debug() const; @@ -946,6 +948,7 @@ private: bool ove : 1; bool reimp: 1; bool attached_: 1; + bool privateSignal_: 1; QList params; const FunctionNode* rf; const PropertyNode* ap; diff --git a/src/tools/qdoc/tokenizer.cpp b/src/tools/qdoc/tokenizer.cpp index 6bfa678bc6..68c6fb7831 100644 --- a/src/tools/qdoc/tokenizer.cpp +++ b/src/tools/qdoc/tokenizer.cpp @@ -78,7 +78,8 @@ static const char *kwords[] = { "QT3_SUPPORT", "QT3_SUPPORT_CONSTRUCTOR", "QT3_MOC_SUPPORT", - "QDOC_PROPERTY" + "QDOC_PROPERTY", + "QPrivateSignal" }; static const int KwordHashTableSize = 4096; diff --git a/src/tools/qdoc/tokenizer.h b/src/tools/qdoc/tokenizer.h index 5827ce9b7d..2b79320567 100644 --- a/src/tools/qdoc/tokenizer.h +++ b/src/tools/qdoc/tokenizer.h @@ -74,8 +74,8 @@ enum { Tok_Eoi, Tok_Ampersand, Tok_Aster, Tok_Caret, Tok_LeftParen, Tok_Q_DECLARE_FLAGS, Tok_Q_SIGNALS, Tok_Q_SLOTS, Tok_QT_COMPAT, Tok_QT_COMPAT_CONSTRUCTOR, Tok_QT_DEPRECATED, Tok_QT_MOC_COMPAT, Tok_QT_MODULE, Tok_QT3_SUPPORT, Tok_QT3_SUPPORT_CONSTRUCTOR, - Tok_QT3_MOC_SUPPORT, Tok_QDOC_PROPERTY, - Tok_FirstKeyword = Tok_char, Tok_LastKeyword = Tok_QDOC_PROPERTY }; + Tok_QT3_MOC_SUPPORT, Tok_QDOC_PROPERTY, Tok_QPrivateSignal, + Tok_FirstKeyword = Tok_char, Tok_LastKeyword = Tok_QPrivateSignal }; /* The Tokenizer class implements lexical analysis of C++ source -- cgit v1.2.3