Add a documentation file hint to function/enum type entries

Task-number: PYSIDE-1106
Change-Id: I28b3fa16f37d0d689956b55caa949307472efda6
Reviewed-by: Shyamnath Premnadh <Shyamnath.Premnadh@qt.io>

7 files changed, 65 insertions, 13 deletions

diff --git a/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml b/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml
index 2011bd3e7..2dbafc8b8 100644
--- a/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml
+++ b/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml
@@ -38,10 +38,11 @@
     </function>
     <function signature="qCompress(const uchar*,qsizetype,int)"/>
     <function signature="qCompress(const QByteArray&amp;,int)"/>
-    <function signature="qUncompress(const uchar*,qsizetype)"/>
-    <function signature="qUncompress(const QByteArray&amp;)"/>
-    <function signature="qFormatLogMessage(QtMsgType,const QMessageLogContext&amp;,const QString&amp;)"/>
-    <function signature="qSetMessagePattern(const QString&amp;)"/>
+    <function signature="qUncompress(const uchar*,qsizetype)" doc-file="qbytearray"/>
+    <function signature="qUncompress(const QByteArray&amp;)" doc-file="qbytearray"/>
+    <function signature="qFormatLogMessage(QtMsgType,const QMessageLogContext&amp;,const QString&amp;)"
+              doc-file="qtlogging"/>
+    <function signature="qSetMessagePattern(const QString&amp;)" doc-file="qtlogging"/>
 
     <inject-code class="native" position="beginning" file="../glue/qtcore.cpp" snippet="include-pyside"/>
     <inject-code class="native" position="beginning" file="../glue/qtcore.cpp"
@@ -135,10 +136,10 @@
 
   <!-- From Qt4.6 ^^^ -->
 
-  <enum-type name="QtMsgType"/>
-  <enum-type name="QCborSimpleType"/>
-  <enum-type name="QCborKnownTags"/>
-  <enum-type name="QCborTag"/>
+  <enum-type name="QtMsgType" doc-file="qtlogging"/>
+  <enum-type name="QCborSimpleType" doc-file="qtcborcommon"/>
+  <enum-type name="QCborKnownTags" doc-file="qtcborcommon"/>
+  <enum-type name="QCborTag" doc-file="qtcborcommon"/>
 
   <primitive-type name="qint8"/>
   <primitive-type name="qint16"/>
diff --git a/sources/pyside6/PySide6/QtQml/typesystem_qml.xml b/sources/pyside6/PySide6/QtQml/typesystem_qml.xml
index b5538dcba..a1202d49b 100644
--- a/sources/pyside6/PySide6/QtQml/typesystem_qml.xml
+++ b/sources/pyside6/PySide6/QtQml/typesystem_qml.xml
@@ -37,7 +37,7 @@
              in generator tests folder. -->
     </primitive-type>
 
-    <enum-type name="QQmlModuleImportSpecialVersions"/>
+    <enum-type name="QQmlModuleImportSpecialVersions" doc-file="qqmlengine"/>
 
     <!-- expose QQmlIncubationController::incubateWhile() (see
          QtQml_VolatileBoolTypeF/pysideqmlvolatilebool.h) -->
@@ -97,7 +97,7 @@
             <modify-argument index="return" pyi-type="Optional[PySide6.QtQml.QJSEngine]"/>
         </modify-function>
     </function>
-    <function signature="qmlClearTypeRegistrations()"/>
+    <function signature="qmlClearTypeRegistrations()" doc-file="qqmlengine"/>
     <function signature="qmlContext(const QObject*)">
         <modify-function>
             <modify-argument index="return" pyi-type="Optional[PySide6.QtQml.QQmlContext]"/>
@@ -108,9 +108,9 @@
             <modify-argument index="return" pyi-type="Optional[PySide6.QtQml.QQmlEngine]"/>
         </modify-function>
      </function>
-    <function signature="qmlProtectModule(const char*,int)"/>
-    <function signature="qmlRegisterModule(const char*,int,int)"/>
-    <function signature="qmlTypeId(const char*,int,int,const char*)"/>
+    <function signature="qmlProtectModule(const char*,int)" doc-file="qqmlengine"/>
+    <function signature="qmlRegisterModule(const char*,int,int)" doc-file="qqmlengine"/>
+    <function signature="qmlTypeId(const char*,int,int,const char*)" doc-file="qqmlengine"/>
     <function signature="qmlRegisterType(const QUrl &amp;,const char *,int,int,const char *)"/>
     <function signature="qmlRegisterSingletonType(const QUrl &amp;,const char *,int,int,const char *)"/>
     <function signature="qmlRegisterUncreatableMetaObject(const QMetaObject&amp;,const char*,int,int, const char*,const QString&amp;)"/>
diff --git a/sources/shiboken6/ApiExtractor/enumtypeentry.h b/sources/shiboken6/ApiExtractor/enumtypeentry.h
index c7fe54d01..3360d7db5 100644
--- a/sources/shiboken6/ApiExtractor/enumtypeentry.h
+++ b/sources/shiboken6/ApiExtractor/enumtypeentry.h
@@ -37,6 +37,9 @@ public:
     void addEnumValueRejection(const QString &name);
     QStringList enumValueRejections() const;
 
+    QString docFile() const;
+    void setDocFile(const QString &df);
+
     TypeEntry *clone() const override;
 #ifndef QT_NO_DEBUG_STREAM
     void formatDebug(QDebug &d) const override;
diff --git a/sources/shiboken6/ApiExtractor/functiontypeentry.h b/sources/shiboken6/ApiExtractor/functiontypeentry.h
index 8042f950a..53aa1fad6 100644
--- a/sources/shiboken6/ApiExtractor/functiontypeentry.h
+++ b/sources/shiboken6/ApiExtractor/functiontypeentry.h
@@ -19,6 +19,9 @@ public:
     bool hasSignature(const QString& signature) const;
     void addSignature(const QString& signature);
 
+    QString docFile() const;
+    void setDocFile(const QString &df);
+
     TypeEntry *clone() const override;
 
 #ifndef QT_NO_DEBUG_STREAM
diff --git a/sources/shiboken6/ApiExtractor/typesystem.cpp b/sources/shiboken6/ApiExtractor/typesystem.cpp
index 0ee70e683..624a4b68d 100644
--- a/sources/shiboken6/ApiExtractor/typesystem.cpp
+++ b/sources/shiboken6/ApiExtractor/typesystem.cpp
@@ -1030,6 +1030,7 @@ public:
     QStringList m_rejectedEnums;
     FlagsTypeEntryPtr m_flags;
     QString m_cppType;
+    QString m_docFile;
     TypeSystem::PythonEnumType m_pythonEnumType = TypeSystem::PythonEnumType::Unspecified;
 };
 
@@ -1123,6 +1124,18 @@ QStringList EnumTypeEntry::enumValueRejections() const
     return d->m_rejectedEnums;
 }
 
+QString EnumTypeEntry::docFile() const
+{
+    S_D(const EnumTypeEntry);
+    return d->m_docFile;
+}
+
+void EnumTypeEntry::setDocFile(const QString &df)
+{
+    S_D(EnumTypeEntry);
+    d->m_docFile = df;
+}
+
 TypeEntry *EnumTypeEntry::clone() const
 {
     S_D(const EnumTypeEntry);
@@ -2330,6 +2343,7 @@ public:
     }
 
     QStringList m_signatures;
+    QString m_docFile;
 };
 
 FunctionTypeEntry::FunctionTypeEntry(const QString &entryName, const QString &signature,
@@ -2357,6 +2371,18 @@ bool FunctionTypeEntry::hasSignature(const QString &signature) const
     return d->m_signatures.contains(signature);
 }
 
+QString FunctionTypeEntry::docFile() const
+{
+    S_D(const FunctionTypeEntry);
+    return d->m_docFile;
+}
+
+void FunctionTypeEntry::setDocFile(const QString &df)
+{
+    S_D(FunctionTypeEntry);
+    d->m_docFile = df;
+}
+
 TypeEntry *FunctionTypeEntry::clone() const
 {
     S_D(const FunctionTypeEntry);
diff --git a/sources/shiboken6/ApiExtractor/typesystemparser.cpp b/sources/shiboken6/ApiExtractor/typesystemparser.cpp
index d0abe6416..608f268e7 100644
--- a/sources/shiboken6/ApiExtractor/typesystemparser.cpp
+++ b/sources/shiboken6/ApiExtractor/typesystemparser.cpp
@@ -61,6 +61,7 @@ constexpr auto defaultSuperclassAttribute = "default-superclass"_L1;
 constexpr auto deleteInMainThreadAttribute = "delete-in-main-thread"_L1;
 constexpr auto deprecatedAttribute = "deprecated"_L1;
 constexpr auto disableWrapperAttribute = "disable-wrapper"_L1;
+constexpr auto docFileAttribute = "doc-file"_L1;
 constexpr auto exceptionHandlingAttribute = "exception-handling"_L1;
 constexpr auto extensibleAttribute = "extensible"_L1;
 constexpr auto fileNameAttribute = "file-name"_L1;
@@ -1596,6 +1597,8 @@ EnumTypeEntryPtr
         } else if (name == u"lower-bound") {
             qCWarning(lcShiboken, "%s",
                       qPrintable(msgUnimplementedAttributeWarning(reader, name)));
+        } else if (name == docFileAttribute) {
+            entry->setDocFile(attributes->takeAt(i).value().toString());
         } else if (name == forceIntegerAttribute) {
             qCWarning(lcShiboken, "%s",
                       qPrintable(msgUnimplementedAttributeWarning(reader, name)));
@@ -1724,10 +1727,13 @@ FunctionTypeEntryPtr
     const bool hasModification = attributes->size() < oldAttributesSize;
 
     QString originalSignature;
+    QString docFile;
     for (auto i = attributes->size() - 1; i >= 0; --i) {
         const auto name = attributes->at(i).qualifiedName();
         if (name == signatureAttribute)
             originalSignature = attributes->takeAt(i).value().toString().simplified();
+        else if (name == docFileAttribute)
+            docFile = attributes->takeAt(i).value().toString();
     }
 
     const QString signature = TypeDatabase::normalizedSignature(originalSignature);
@@ -1748,6 +1754,7 @@ FunctionTypeEntryPtr
         auto result = std::make_shared<FunctionTypeEntry>(name, signature, since,
                                                           currentParentTypeEntry());
         result->setTargetLangPackage(m_defaultPackage);
+        result->setDocFile(docFile);
         applyCommonAttributes(reader, result, attributes);
         return result;
     }
diff --git a/sources/shiboken6/doc/typesystem_specifying_types.rst b/sources/shiboken6/doc/typesystem_specifying_types.rst
index 44d33f349..86c0899ad 100644
--- a/sources/shiboken6/doc/typesystem_specifying_types.rst
+++ b/sources/shiboken6/doc/typesystem_specifying_types.rst
@@ -256,6 +256,7 @@ and it is a child of the :ref:`typesystem` node. Use
             flags="yes | no"
             flags-revision="..."
             cpp-type = "..."
+            doc-file = "..."
             python-type = "IntEnum | IntFlag"
             lower-bound="..."
             upper-bound="..."
@@ -290,6 +291,11 @@ The *optional* **cpp-type** attribute specifies a C++ to be used for
 casting values. This can be useful for large values triggering MSVC
 signedness issues.
 
+The *optional* **doc-file** attribute specifies the base name of the C++ or
+``.qdoc`` file indicated by ``\relates`` or ``\headerfile`` in ``qdoc``, to
+which the documentation of the enumeration is to be added and displayed in the
+case its a global enumeration. This attribute is for ``qdoc`` only.
+
 The **revision** attribute can be used to specify a revision for each type, easing the
 production of ABI compatible bindings.
 
@@ -769,6 +775,7 @@ and may contain a :ref:`modify-function` child node.
     <typesystem>
         <function signature="..." rename="..." since="..."
                   allow-thread="true | auto | false"
+                  doc-file = "..."
                   exception-handling="off | auto-off | auto-on | on"
                   overload-number="number"
                   snake-case="yes | no | both" />
@@ -782,6 +789,11 @@ the function was introduced.
 
 The *optional* **rename** attribute is used to modify the function name.
 
+The *optional* **doc-file** attribute specifies the base name of the C++ or
+``.qdoc`` file indicated by ``\relates`` or ``\headerfile`` in ``qdoc``, to
+which the documentation of the function is to be added and displayed in the
+case its a global function. This attribute is for ``qdoc`` only.
+
 For the *optional* attributes **allow-thread**, **exception-handling**,
 **overload-number** and **snake-case**, see :ref:`modify-function`.