shiboken: Enable specifying names for a parameters of added functions

Introduce a way to specify a name for a parameter using '@'
delimiters.

Fixes: PYSIDE-1017
Change-Id: I3ae505c104a64413ca2bad628d9f9d3e04bb5b88
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
 

5 files changed, 59 insertions, 10 deletions

diff --git a/sources/shiboken2/ApiExtractor/abstractmetabuilder.cpp b/sources/shiboken2/ApiExtractor/abstractmetabuilder.cpp
index 67489b151..170a8e1d4 100644
--- a/sources/shiboken2/ApiExtractor/abstractmetabuilder.cpp
+++ b/sources/shiboken2/ApiExtractor/abstractmetabuilder.cpp
@@ -1615,11 +1615,11 @@ AbstractMetaFunction* AbstractMetaBuilderPrivate::traverseFunction(const AddedFu
     metaFunction->setType(translateType(addedFunc->returnType()));
 
 
-    QVector<AddedFunction::TypeInfo> args = addedFunc->arguments();
+    const auto &args = addedFunc->arguments();
     AbstractMetaArgumentList metaArguments;
 
     for (int i = 0; i < args.count(); ++i) {
-        AddedFunction::TypeInfo& typeInfo = args[i];
+        const AddedFunction::TypeInfo& typeInfo = args.at(i).typeInfo;
         AbstractMetaArgument *metaArg = new AbstractMetaArgument;
         AbstractMetaType *type = translateType(typeInfo);
         if (Q_UNLIKELY(!type)) {
@@ -1630,6 +1630,8 @@ AbstractMetaFunction* AbstractMetaBuilderPrivate::traverseFunction(const AddedFu
             return nullptr;
         }
         type->decideUsagePattern();
+        if (!args.at(i).name.isEmpty())
+            metaArg->setName(args.at(i).name);
         metaArg->setType(type);
         metaArg->setArgumentIndex(i);
         metaArg->setDefaultValueExpression(typeInfo.defaultValue);
diff --git a/sources/shiboken2/ApiExtractor/tests/testaddfunction.cpp b/sources/shiboken2/ApiExtractor/tests/testaddfunction.cpp
index 8c443527e..c50084b8e 100644
--- a/sources/shiboken2/ApiExtractor/tests/testaddfunction.cpp
+++ b/sources/shiboken2/ApiExtractor/tests/testaddfunction.cpp
@@ -46,17 +46,21 @@ void TestAddFunction::testParsingFuncNameAndConstness()
     QCOMPARE(retval.isReference, false);
 
     // test with a ugly template as argument and other ugly stuff
-    const char sig2[] = "    _fu__nc_       (  type1, const type2, const Abc<int& , C<char*> *   >  * *, const type3* const    )   const ";
+    const char sig2[] = "    _fu__nc_       (  type1, const type2, const Abc<int& , C<char*> *   >  * *@my_name@, const type3* const    )   const ";
     AddedFunction f2(QLatin1String(sig2), QLatin1String("const Abc<int& , C<char*> *   >  * *"));
     QCOMPARE(f2.name(), QLatin1String("_fu__nc_"));
-    QVector< AddedFunction::TypeInfo > args = f2.arguments();
+    const auto &args = f2.arguments();
     QCOMPARE(args.count(), 4);
     retval = f2.returnType();
     QCOMPARE(retval.name, QLatin1String("Abc<int& , C<char*> *   >"));
     QCOMPARE(retval.indirections, 2);
     QCOMPARE(retval.isConstant, true);
     QCOMPARE(retval.isReference, false);
-    retval = args[2];
+    retval = args.at(2).typeInfo;
+    QVERIFY(args.at(0).name.isEmpty());
+    QVERIFY(args.at(1).name.isEmpty());
+    QCOMPARE(args.at(2).name, QLatin1String("my_name"));
+    QVERIFY(args.at(3).name.isEmpty());
     QCOMPARE(retval.name, QLatin1String("Abc<int& , C<char*> *   >"));
     QCOMPARE(retval.indirections, 2);
     QCOMPARE(retval.isConstant, true);
diff --git a/sources/shiboken2/ApiExtractor/typesystem.cpp b/sources/shiboken2/ApiExtractor/typesystem.cpp
index 434134be9..344313e87 100644
--- a/sources/shiboken2/ApiExtractor/typesystem.cpp
+++ b/sources/shiboken2/ApiExtractor/typesystem.cpp
@@ -3279,7 +3279,9 @@ QString FunctionModification::toString() const
     return str;
 }
 
-static AddedFunction::TypeInfo parseType(const QString& signature, int startPos = 0, int* endPos = 0)
+static AddedFunction::TypeInfo parseType(const QString& signature,
+                                         int startPos = 0, int *endPos = nullptr,
+                                         QString *argumentName = nullptr)
 {
     AddedFunction::TypeInfo result;
     static const QRegularExpression regex(QLatin1String("\\w"));
@@ -3330,6 +3332,19 @@ static AddedFunction::TypeInfo parseType(const QString& signature, int startPos
         paramString.remove(0, sizeof("const")/sizeof(char));
         paramString = paramString.trimmed();
     }
+
+    // Extract argument name from "T<bla,blub>* @foo@"
+    const int nameStartPos = paramString.indexOf(QLatin1Char('@'));
+    if (nameStartPos != -1) {
+        const int nameEndPos = paramString.indexOf(QLatin1Char('@'), nameStartPos + 1);
+        if (nameEndPos > nameStartPos) {
+            if (argumentName)
+                *argumentName = paramString.mid(nameStartPos + 1, nameEndPos - nameStartPos - 1);
+            paramString.remove(nameStartPos, nameEndPos - nameStartPos + 1);
+            paramString = paramString.trimmed();
+        }
+    }
+
     // check reference
     if (paramString.endsWith(QLatin1Char('&'))) {
         result.isReference = true;
@@ -3364,9 +3379,10 @@ AddedFunction::AddedFunction(QString signature, const QString &returnType) :
         m_name = signature.left(endPos).trimmed();
         int signatureLength = signature.length();
         while (endPos < signatureLength) {
-            TypeInfo arg = parseType(signature, endPos, &endPos);
+            QString argumentName;
+            TypeInfo arg = parseType(signature, endPos, &endPos, &argumentName);
             if (!arg.name.isEmpty())
-                m_arguments.append(arg);
+                m_arguments.append({argumentName, arg});
             // end of parameters...
             if (signature[endPos] == QLatin1Char(')'))
                 break;
@@ -3512,6 +3528,19 @@ QDebug operator<<(QDebug d, const AddedFunction::TypeInfo &ti)
     return d;
 }
 
+QDebug operator<<(QDebug d, const AddedFunction::Argument &a)
+{
+    QDebugStateSaver saver(d);
+    d.noquote();
+    d.nospace();
+    d << "Argument(";
+    d << a.typeInfo;
+    if (!a.name.isEmpty())
+        d << ' ' << a.name;
+    d << ')';
+    return d;
+}
+
 QDebug operator<<(QDebug d, const AddedFunction &af)
 {
     QDebugStateSaver saver(d);
diff --git a/sources/shiboken2/ApiExtractor/typesystem.h b/sources/shiboken2/ApiExtractor/typesystem.h
index 2e4578a1d..82a698107 100644
--- a/sources/shiboken2/ApiExtractor/typesystem.h
+++ b/sources/shiboken2/ApiExtractor/typesystem.h
@@ -424,6 +424,12 @@ struct AddedFunction
         bool isReference = false;
     };
 
+    struct Argument
+    {
+        QString name;
+        TypeInfo typeInfo;
+    };
+
     /// Creates a new AddedFunction with a signature and a return type.
     explicit AddedFunction(QString signature, const QString &returnType);
     AddedFunction() = default;
@@ -453,7 +459,7 @@ struct AddedFunction
     }
 
     /// Returns a list of argument type infos.
-    QVector<TypeInfo> arguments() const
+    const QVector<Argument> &arguments() const
     {
         return m_arguments;
     }
@@ -480,7 +486,7 @@ struct AddedFunction
 
 private:
     QString m_name;
-    QVector<TypeInfo> m_arguments;
+    QVector<Argument> m_arguments;
     TypeInfo m_returnType;
     Access m_access = Protected;
     bool m_isConst = false;
@@ -489,6 +495,7 @@ private:
 
 #ifndef QT_NO_DEBUG_STREAM
 QDebug operator<<(QDebug d, const AddedFunction::TypeInfo &ti);
+QDebug operator<<(QDebug d, const AddedFunction::Argument &a);
 QDebug operator<<(QDebug d, const AddedFunction &af);
 #endif
 
diff --git a/sources/shiboken2/doc/typesystem_manipulating_objects.rst b/sources/shiboken2/doc/typesystem_manipulating_objects.rst
index 12b866ad7..c04a4fa27 100644
--- a/sources/shiboken2/doc/typesystem_manipulating_objects.rst
+++ b/sources/shiboken2/doc/typesystem_manipulating_objects.rst
@@ -157,6 +157,13 @@ add-function
 
     The ``since`` attribute specify the API version when this function was added.
 
+    Within the signature, names for the function parameters can be specified by
+    enclosing them within the delimiter *@*:
+
+    .. code-block:: c++
+
+        void foo(int @parameter1@,float)
+
 .. _conversion-rule-on-types:
 
 conversion-rule