qdoc: Allow formal parameters in link targets

This update allows qdoc to handle \l commands for linking
to functions, where the formal parameters are included in
the link target.

For example, \l {QWidget::find(QString name)} will only match
a member function of QWidget that has a single parameter of type
QString. The parameter name is not used in the search.

Change-Id: I8a31c9a7ed632f12a0e6d8a33cbb5cd361098317
Task-number: QTBUG-47286
Reviewed-by: Martin Smith <[email protected]>

Author: Martin Smith

src/corelib/tools/qlist.cpp

@@ -378,7 +378,7 @@ void **QListData::erase(void **xi)
     references into a QVector and non-heap-allocating QLists.
 
     Internally, QList\<T\> is represented as an array of T if
-    If \c{sizeof(T) <= sizeof(void*)} and T has been declared to be
+    \c{sizeof(T) <= sizeof(void*)} and T has been declared to be
     either a \c{Q_MOVABLE_TYPE} or a \c{Q_PRIMITIVE_TYPE} using
     \l {Q_DECLARE_TYPEINFO}. Otherwise, QList\<T\> is represented
     as an array of T* and the items are allocated on the heap.

src/tools/qdoc/codeparser.h

@@ -40,7 +40,6 @@
 QT_BEGIN_NAMESPACE
 
 class Config;
-class Node;
 class QString;
 class QDocDatabase;
 

src/tools/qdoc/cppcodemarker.cpp

@@ -157,11 +157,11 @@ QString CppCodeMarker::markedUpSynopsis(const Node *node,
             synopsis += "(";
             if (!func->parameters().isEmpty()) {
                 //synopsis += QLatin1Char(' ');
-                QList<Parameter>::ConstIterator p = func->parameters().constBegin();
+                QVector<Parameter>::ConstIterator p = func->parameters().constBegin();
                 while (p != func->parameters().constEnd()) {
                     if (p != func->parameters().constBegin())
                         synopsis += ", ";
-                    synopsis += typified((*p).leftType());
+                    synopsis += typified((*p).dataType());
                     if (style != Subpage && !(*p).name().isEmpty())
                         synopsis +=
                                 "<@param>" + protect((*p).name()) + "</@param>";
@@ -328,11 +328,11 @@ QString CppCodeMarker::markedUpQmlItem(const Node* node, bool summary)
             synopsis = name;
         synopsis += QLatin1Char('(');
         if (!func->parameters().isEmpty()) {
-            QList<Parameter>::ConstIterator p = func->parameters().constBegin();
+            QVector<Parameter>::ConstIterator p = func->parameters().constBegin();
             while (p != func->parameters().constEnd()) {
                 if (p != func->parameters().constBegin())
                     synopsis += ", ";
-                synopsis += typified((*p).leftType());
+                synopsis += typified((*p).dataType());
                 if (!(*p).name().isEmpty()) {
                     if (!synopsis.endsWith(QLatin1Char('(')))
                         synopsis += QLatin1Char(' ');

src/tools/qdoc/cppcodeparser.cpp

@@ -54,6 +54,7 @@ static bool inMacroCommand_ = false;
 static bool parsingHeaderFile_ = false;
 QStringList CppCodeParser::exampleFiles;
 QStringList CppCodeParser::exampleDirs;
+CppCodeParser* CppCodeParser::cppParser_ = 0;
 
 /*!
   The constructor initializes some regular expressions
@@ -63,6 +64,7 @@ CppCodeParser::CppCodeParser()
     : varComment("/\\*\\s*([a-zA-Z_0-9]+)\\s*\\*/"), sep("(?:<[^>]+>)?::")
 {
     reset();
+    cppParser_ = this;
 }
 
 /*!
@@ -374,12 +376,12 @@ Node* CppCodeParser::processTopicCommand(const Doc& doc,
             }
             else {
                 func->setMetaness(FunctionNode::MacroWithParams);
-                QList<Parameter> params = func->parameters();
+                QVector<Parameter> params = func->parameters();
                 for (int i = 0; i < params.size(); ++i) {
                     Parameter &param = params[i];
-                    if (param.name().isEmpty() && !param.leftType().isEmpty()
-                            && param.leftType() != "...")
-                        param = Parameter("", "", param.leftType());
+                    if (param.name().isEmpty() && !param.dataType().isEmpty()
+                            && param.dataType() != "...")
+                        param = Parameter("", "", param.dataType());
                 }
                 func->setParameters(params);
             }
@@ -1308,23 +1310,23 @@ bool CppCodeParser::matchDataType(CodeChunk *dataType, QString *var)
 
 /*!
   Parse the next function parameter, if there is one, and
-  append it to parameter list \a p. Return true if a parameter
-  is parsed and appended to \a p. Otherwise return false.
+  append it to parameter vector \a pvect. Return true if
+  a parameter is parsed and appended to \a pvect.
+  Otherwise return false.
  */
-bool CppCodeParser::matchParameter(ParsedParameterList& pplist)
+bool CppCodeParser::matchParameter(QVector<Parameter>& pvect, bool& isQPrivateSignal)
 {
-    ParsedParameter pp;
     if (match(Tok_QPrivateSignal)) {
-        pp.qPrivateSignal_ = true;
-        pplist.append(pp);
+        isQPrivateSignal = true;
         return true;
     }
 
+    Parameter p;
     CodeChunk chunk;
-    if (!matchDataType(&chunk, &pp.name_)) {
+    if (!matchDataType(&chunk, &p.name_)) {
         return false;
     }
-    pp.dataType_ = chunk.toString();
+    p.dataType_ = chunk.toString();
     chunk.clear();
     match(Tok_Comment);
     if (match(Tok_Equal)) {
@@ -1336,8 +1338,8 @@ bool CppCodeParser::matchParameter(ParsedParameterList& pplist)
             readToken();
         }
     }
-    pp.defaultValue_ = chunk.toString();
-    pplist.append(pp);
+    p.defaultValue_ = chunk.toString();
+    pvect.append(p);
     return true;
 }
 
@@ -1542,10 +1544,11 @@ bool CppCodeParser::matchFunctionDecl(Aggregate *parent,
     readToken();
 
     // A left paren was seen. Parse the parameters
-    ParsedParameterList pplist;
+    bool isQPrivateSignal = false;
+    QVector<Parameter> pvect;
     if (tok != Tok_RightParen) {
         do {
-            if (!matchParameter(pplist))
+            if (!matchParameter(pvect, isQPrivateSignal))
                 return false;
         } while (match(Tok_Comma));
     }
@@ -1629,13 +1632,10 @@ bool CppCodeParser::matchFunctionDecl(Aggregate *parent,
         func->setStatic(matched_static);
         func->setConst(matchedConst);
         func->setVirtualness(virtuality);
-        if (!pplist.isEmpty()) {
-            foreach (const ParsedParameter& pp, pplist) {
-                if (pp.qPrivateSignal_)
-                    func->setPrivateSignal();
-                else
-                    func->addParameter(Parameter(pp.dataType_, "", pp.name_, pp.defaultValue_));
-            }
+        if (isQPrivateSignal)
+            func->setPrivateSignal();
+        if (!pvect.isEmpty()) {
+            func->setParameters(pvect);
         }
     }
     if (parentPathPtr != 0)
@@ -2416,6 +2416,34 @@ bool CppCodeParser::makeFunctionNode(const QString& signature,
     return ok;
 }
 
+/*!
+  This function uses a Tokenizer to parse the \a parameters of a
+  function into the parameter vector \a {pvect}.
+ */
+bool CppCodeParser::parseParameters(const QString& parameters,
+                                    QVector<Parameter>& pvect,
+                                    bool& isQPrivateSignal)
+{
+    Tokenizer* outerTokenizer = tokenizer;
+    int outerTok = tok;
+
+    QByteArray latin1 = parameters.toLatin1();
+    Tokenizer stringTokenizer(Location(), latin1);
+    stringTokenizer.setParsingFnOrMacro(true);
+    tokenizer = &stringTokenizer;
+    readToken();
+
+    inMacroCommand_ = false;
+    do {
+        if (!matchParameter(pvect, isQPrivateSignal))
+            return false;
+    } while (match(Tok_Comma));
+
+    tokenizer = outerTokenizer;
+    tok = outerTok;
+    return true;
+}
+
 /*!
   Create a new FunctionNode for a QML method or signal, as
   specified by \a type, as a child of \a parent. \a sig is

src/tools/qdoc/cppcodeparser.h

@@ -51,16 +51,6 @@ class CppCodeParser : public CodeParser
 {
     Q_DECLARE_TR_FUNCTIONS(QDoc::CppCodeParser)
 
-    struct ParsedParameter {
-        bool qPrivateSignal_;
-        QString dataType_;
-        QString name_;
-        QString defaultValue_;
-      ParsedParameter() : qPrivateSignal_(false) { }
-    };
-    friend class QTypeInfo<ParsedParameter>;
-    typedef QVector<ParsedParameter> ParsedParameterList;
-
     struct ExtraFuncData {
         Aggregate* root; // Used as the parent.
         Node::NodeType type; // The node type: Function, etc.
@@ -74,6 +64,7 @@ class CppCodeParser : public CodeParser
 public:
     CppCodeParser();
     ~CppCodeParser();
+    static CppCodeParser* cppParser() { return cppParser_; }
 
     virtual void initializeParser(const Config& config) Q_DECL_OVERRIDE;
     virtual void terminateParser() Q_DECL_OVERRIDE;
@@ -84,6 +75,7 @@ class CppCodeParser : public CodeParser
     virtual void parseSourceFile(const Location& location, const QString& filePath) Q_DECL_OVERRIDE;
     virtual void doneParsingHeaderFiles() Q_DECL_OVERRIDE;
     virtual void doneParsingSourceFiles() Q_DECL_OVERRIDE;
+    bool parseParameters(const QString& parameters, QVector<Parameter>& pvect, bool& isQPrivateSignal);
 
 protected:
     const QSet<QString>& topicCommands();
@@ -126,7 +118,7 @@ class CppCodeParser : public CodeParser
     bool matchTemplateAngles(CodeChunk *type = 0);
     bool matchTemplateHeader();
     bool matchDataType(CodeChunk *type, QString *var = 0);
-    bool matchParameter(ParsedParameterList& pplist);
+    bool matchParameter(QVector<Parameter>& pvect, bool& isQPrivateSignal);
     bool matchFunctionDecl(Aggregate *parent,
                            QStringList *parentPathPtr,
                            FunctionNode **funcPtr,
@@ -184,10 +176,10 @@ class CppCodeParser : public CodeParser
 
     static QStringList exampleFiles;
     static QStringList exampleDirs;
+    static CppCodeParser* cppParser_;
     QString exampleNameFilter;
     QString exampleImageFilter;
 };
-Q_DECLARE_TYPEINFO(CppCodeParser::ParsedParameter, Q_MOVABLE_TYPE);
 
 #define COMMAND_ABSTRACT                Doc::alias("abstract")
 #define COMMAND_CLASS                   Doc::alias("class")

src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc

@@ -1839,8 +1839,13 @@
     \li \c {\l QWidget} - The name of a class documented with the \l
     {class-command} {\\class} command.
 
-    \li \c {\l QWidget::sizeHint()} - The name of a member function,
-    documented with or without an \l {fn-command} {\\fn} command.
+    \li \c {\l QWidget::sizeHint()} - The signature of a function without
+    parameters. If a matching function without parameters can't be found,
+    the link is satisfied with the first matching function found.
+
+    \li \c {\l QWidget::removeAction(QAction* action)} - The signature
+    of a function with parameters. If an exact match is not found, the
+    link is not satisfied and qdoc reports a \e {Can't link to...} error.
 
     \li \c {\l <QtGlobal>} - The subject of a \l {headerfile-command}
     {\\headerfile} command.

src/tools/qdoc/generator.cpp

@@ -804,9 +804,9 @@ void Generator::generateBody(const Node *node, CodeMarker *marker)
         else if (node->type() == Node::Function) {
             const FunctionNode *func = static_cast<const FunctionNode *>(node);
             QSet<QString> definedParams;
-            QList<Parameter>::ConstIterator p = func->parameters().constBegin();
+            QVector<Parameter>::ConstIterator p = func->parameters().constBegin();
             while (p != func->parameters().constEnd()) {
-                if ((*p).name().isEmpty() && (*p).leftType() != QLatin1String("...")
+                if ((*p).name().isEmpty() && (*p).dataType() != QLatin1String("...")
                         && func->name() != QLatin1String("operator++")
                         && func->name() != QLatin1String("operator--")) {
                     node->doc().location().warning(tr("Missing parameter name"));
@@ -836,7 +836,7 @@ void Generator::generateBody(const Node *node, CodeMarker *marker)
                     else if (!(*a).isEmpty() && !documentedParams.contains(*a)) {
                         bool needWarning = (func->status() > Node::Obsolete);
                         if (func->overloadNumber() > 0) {
-                            FunctionNode *primaryFunc = func->parent()->findFunctionNode(func->name());
+                            FunctionNode *primaryFunc = func->parent()->findFunctionNode(func->name(), QString());
                             if (primaryFunc) {
                                 foreach (const Parameter &param,
                                          primaryFunc->parameters()) {
@@ -1504,7 +1504,7 @@ void Generator::generateOverloadedSignal(const Node* node, CodeMarker* marker)
         if (i != 0)
             code += ", ";
         const Parameter &p = func->parameters().at(i);
-        code += p.leftType() + p.rightType();
+        code += p.dataType() + p.rightType();
     }
 
     code += ")";
@@ -1516,7 +1516,7 @@ void Generator::generateOverloadedSignal(const Node* node, CodeMarker* marker)
         if (i != 0)
             code += ", ";
         const Parameter &p = func->parameters().at(i);
-        code += p.leftType();
+        code += p.dataType();
         if (code[code.size()-1].isLetterOrNumber())
             code += " ";
         code += p.name()  + p.rightType();
@@ -2049,22 +2049,22 @@ void Generator::supplementAlsoList(const Node *node, QList<Text> &alsoList)
             if (func->name().startsWith("set") && func->name().size() >= 4) {
                 alternateName = func->name()[3].toLower();
                 alternateName += func->name().mid(4);
-                alternateFunc = func->parent()->findFunctionNode(alternateName);
+                alternateFunc = func->parent()->findFunctionNode(alternateName, QString());
 
                 if (!alternateFunc) {
                     alternateName = "is" + func->name().mid(3);
-                    alternateFunc = func->parent()->findFunctionNode(alternateName);
+                    alternateFunc = func->parent()->findFunctionNode(alternateName, QString());
                     if (!alternateFunc) {
                         alternateName = "has" + func->name().mid(3);
-                        alternateFunc = func->parent()->findFunctionNode(alternateName);
+                        alternateFunc = func->parent()->findFunctionNode(alternateName, QString());
                     }
                 }
             }
             else if (!func->name().isEmpty()) {
                 alternateName = "set";
                 alternateName += func->name()[0].toUpper();
                 alternateName += func->name().mid(1);
-                alternateFunc = func->parent()->findFunctionNode(alternateName);
+                alternateFunc = func->parent()->findFunctionNode(alternateName, QString());
             }
 
             if (alternateFunc && alternateFunc->access() != Node::Private) {