shiboken6/doc generator: Extract method to resolve links to QtXmlToSphinxDocGeneratorInterface

Extract the private struct LinkContext to a public struct
QtXmlToSphinxLink with debug operator and add a resolve method to
QtXmlToSphinxDocGeneratorInterface.

Task-number: PYSIDE-1112
Change-Id: I91b3bc45ebc530394a3e77c56b05dd5b740e8985
Reviewed-by: Christian Tismer <tismer@stackless.com>
(cherry picked from commit 991cfb9376275e1ab259f0a9b95302bc56ba7127)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

7 files changed, 97 insertions, 58 deletions

diff --git a/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp b/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp
index d1de31cef..fd4716e0a 100644
--- a/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp
+++ b/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp
@@ -1140,3 +1140,8 @@ const QLoggingCategory &QtDocGenerator::loggingCategory() const
 {
     return lcShibokenDoc();
 }
+
+QtXmlToSphinxLink QtDocGenerator::resolveLink(const QtXmlToSphinxLink &link) const
+{
+    return link;
+}
diff --git a/sources/shiboken6/generator/qtdoc/qtdocgenerator.h b/sources/shiboken6/generator/qtdoc/qtdocgenerator.h
index 2b18d1edd..ab2f2fd45 100644
--- a/sources/shiboken6/generator/qtdoc/qtdocgenerator.h
+++ b/sources/shiboken6/generator/qtdoc/qtdocgenerator.h
@@ -66,6 +66,7 @@ public:
     QString resolveContextForMethod(const QString &context,
                                     const QString &methodName) const override;
     const QLoggingCategory &loggingCategory() const override;
+    QtXmlToSphinxLink resolveLink(const QtXmlToSphinxLink &) const override;
 
 protected:
     bool shouldGenerate(const AbstractMetaClass *) const override;
diff --git a/sources/shiboken6/generator/qtdoc/qtxmltosphinx.cpp b/sources/shiboken6/generator/qtdoc/qtxmltosphinx.cpp
index 6bca4498c..d74982210 100644
--- a/sources/shiboken6/generator/qtdoc/qtxmltosphinx.cpp
+++ b/sources/shiboken6/generator/qtdoc/qtxmltosphinx.cpp
@@ -75,58 +75,61 @@ static bool isHttpLink(const QString &ref)
     return ref.startsWith(u"http://") || ref.startsWith(u"https://");
 }
 
-struct QtXmlToSphinx::LinkContext
+QDebug operator<<(QDebug d, const QtXmlToSphinxLink &l)
 {
-    enum Type
-    {
-        Method = 0x1, Function = 0x2,
-        FunctionMask = Method | Function,
-        Class = 0x4, Attribute = 0x8, Module = 0x10,
-        Reference = 0x20, External= 0x40
+    static const QHash<QtXmlToSphinxLink::Type, const char *> typeName = {
+        {QtXmlToSphinxLink::Method, "Method"},
+        {QtXmlToSphinxLink::Function, "Function"},
+        {QtXmlToSphinxLink::Class, "Class"},
+        {QtXmlToSphinxLink::Attribute, "Attribute"},
+        {QtXmlToSphinxLink::Module, "Module"},
+        {QtXmlToSphinxLink::Reference, "Reference"},
+        {QtXmlToSphinxLink::External, "External"},
     };
 
-    enum Flags { InsideBold = 0x1, InsideItalic = 0x2 };
-
-    explicit LinkContext(const QString &ref) : linkRef(ref) {}
-
-    QString linkRef;
-    QString linkText;
-    Type type = Reference;
-    int flags = 0;
-};
+    QDebugStateSaver saver(d);
+    d.noquote();
+    d.nospace();
+    d << "QtXmlToSphinxLinkContext(" << typeName.value(l.type, "") << ", ref=\""
+      << l.linkRef << '"';
+    if (!l.linkText.isEmpty())
+        d << ", text=\"" << l.linkText << '"';
+    d << ')';
+    return d;
+}
 
-static const char *linkKeyWord(QtXmlToSphinx::LinkContext::Type type)
+static const char *linkKeyWord(QtXmlToSphinxLink::Type type)
 {
     switch (type) {
-    case QtXmlToSphinx::LinkContext::Method:
+    case QtXmlToSphinxLink::Method:
         return ":meth:";
-    case QtXmlToSphinx::LinkContext::Function:
+    case QtXmlToSphinxLink::Function:
         return ":func:";
-    case QtXmlToSphinx::LinkContext::Class:
+    case QtXmlToSphinxLink::Class:
         return ":class:";
-    case QtXmlToSphinx::LinkContext::Attribute:
+    case QtXmlToSphinxLink::Attribute:
         return ":attr:";
-    case QtXmlToSphinx::LinkContext::Module:
+    case QtXmlToSphinxLink::Module:
         return ":mod:";
-    case QtXmlToSphinx::LinkContext::Reference:
+    case QtXmlToSphinxLink::Reference:
         return ":ref:";
-    case QtXmlToSphinx::LinkContext::External:
+    case QtXmlToSphinxLink::External:
         break;
-    case QtXmlToSphinx::LinkContext::FunctionMask:
+    case QtXmlToSphinxLink::FunctionMask:
         break;
      }
     return "";
 }
 
-TextStream &operator<<(TextStream &str, const QtXmlToSphinx::LinkContext &linkContext)
+TextStream &operator<<(TextStream &str, const QtXmlToSphinxLink &linkContext)
 {
     // Temporarily turn off bold/italic since links do not work within
-    if (linkContext.flags & QtXmlToSphinx::LinkContext::InsideBold)
+    if (linkContext.flags & QtXmlToSphinxLink::InsideBold)
         str << "**";
-    else if (linkContext.flags & QtXmlToSphinx::LinkContext::InsideItalic)
+    else if (linkContext.flags & QtXmlToSphinxLink::InsideItalic)
         str << '*';
     str << ' ' << linkKeyWord(linkContext.type) << '`';
-    const bool isExternal = linkContext.type == QtXmlToSphinx::LinkContext::External;
+    const bool isExternal = linkContext.type == QtXmlToSphinxLink::External;
     if (!linkContext.linkText.isEmpty()) {
         writeEscapedRstText(str, linkContext.linkText);
         if (isExternal && !linkContext.linkText.endsWith(QLatin1Char(' ')))
@@ -134,7 +137,7 @@ TextStream &operator<<(TextStream &str, const QtXmlToSphinx::LinkContext &linkCo
         str << '<';
     }
     // Convert page titles to RST labels
-    str << (linkContext.type == QtXmlToSphinx::LinkContext::Reference
+    str << (linkContext.type == QtXmlToSphinxLink::Reference
         ? toRstLabel(linkContext.linkRef) : linkContext.linkRef);
     if (!linkContext.linkText.isEmpty())
         str << '>';
@@ -142,9 +145,9 @@ TextStream &operator<<(TextStream &str, const QtXmlToSphinx::LinkContext &linkCo
     if (isExternal)
         str << '_';
     str << ' ';
-    if (linkContext.flags & QtXmlToSphinx::LinkContext::InsideBold)
+    if (linkContext.flags & QtXmlToSphinxLink::InsideBold)
         str << "**";
-    else if (linkContext.flags & QtXmlToSphinx::LinkContext::InsideItalic)
+    else if (linkContext.flags & QtXmlToSphinxLink::InsideItalic)
         str << '*';
     return str;
 }
@@ -946,21 +949,21 @@ void QtXmlToSphinx::handleLinkTag(QXmlStreamReader& reader)
     }
 }
 
-QtXmlToSphinx::LinkContext *QtXmlToSphinx::handleLinkStart(const QString &type, QString ref) const
+QtXmlToSphinxLink *QtXmlToSphinx::handleLinkStart(const QString &type, QString ref) const
 {
     ref.replace(QLatin1String("::"), QLatin1String("."));
     ref.remove(QLatin1String("()"));
-    auto *result = new LinkContext(ref);
+    auto *result = new QtXmlToSphinxLink(ref);
 
     if (m_insideBold)
-        result->flags |= LinkContext::InsideBold;
+        result->flags |= QtXmlToSphinxLink::InsideBold;
     else if (m_insideItalic)
-        result->flags |= LinkContext::InsideItalic;
+        result->flags |= QtXmlToSphinxLink::InsideItalic;
 
     if (type == u"external" || isHttpLink(ref)) {
-        result->type = LinkContext::External;
+        result->type = QtXmlToSphinxLink::External;
     } else if (type == functionLinkType() && !m_context.isEmpty()) {
-        result->type = LinkContext::Method;
+        result->type = QtXmlToSphinxLink::Method;
         const auto rawlinklist = QStringView{result->linkRef}.split(QLatin1Char('.'));
         if (rawlinklist.size() == 1 || rawlinklist.constFirst() == m_context) {
             const auto lastRawLink = rawlinklist.constLast().toString();
@@ -971,20 +974,20 @@ QtXmlToSphinx::LinkContext *QtXmlToSphinx::handleLinkStart(const QString &type,
             result->linkRef = m_generator->expandFunction(result->linkRef);
         }
     } else if (type == functionLinkType() && m_context.isEmpty()) {
-        result->type = LinkContext::Function;
+        result->type = QtXmlToSphinxLink::Function;
     } else if (type == classLinkType()) {
-        result->type = LinkContext::Class;
+        result->type = QtXmlToSphinxLink::Class;
         result->linkRef = m_generator->expandClass(m_context, result->linkRef);
     } else if (type == QLatin1String("enum")) {
-        result->type = LinkContext::Attribute;
+        result->type = QtXmlToSphinxLink::Attribute;
     } else if (type == QLatin1String("page")) {
         // Module, external web page or reference
         if (result->linkRef == m_parameters.moduleName)
-            result->type = LinkContext::Module;
+            result->type = QtXmlToSphinxLink::Module;
         else
-            result->type = LinkContext::Reference;
+            result->type = QtXmlToSphinxLink::Reference;
     } else {
-        result->type = LinkContext::Reference;
+        result->type = QtXmlToSphinxLink::Reference;
     }
     return result;
 }
@@ -997,11 +1000,11 @@ QtXmlToSphinx::LinkContext *QtXmlToSphinx::handleLinkStart(const QString &type,
 // <link raw="Qt::Window" href="qt.html#WindowType-enum" type="enum" enum="Qt::WindowType">Qt::Window</link>
 // <link raw="QNetworkSession::reject()" href="qnetworksession.html#reject" type="function">QNetworkSession::reject()</link>
 
-static QString fixLinkText(const QtXmlToSphinx::LinkContext *linkContext,
+static QString fixLinkText(const QtXmlToSphinxLink *linkContext,
                            QString linktext)
 {
-    if (linkContext->type == QtXmlToSphinx::LinkContext::External
-        || linkContext->type == QtXmlToSphinx::LinkContext::Reference) {
+    if (linkContext->type == QtXmlToSphinxLink::External
+        || linkContext->type == QtXmlToSphinxLink::Reference) {
         return linktext;
     }
     // For the language reference documentation, strip the module name.
@@ -1013,21 +1016,21 @@ static QString fixLinkText(const QtXmlToSphinx::LinkContext *linkContext,
          QtXmlToSphinx::stripPythonQualifiers(&linktext);
     if (linkContext->linkRef == linktext)
         return QString();
-    if ((linkContext->type & QtXmlToSphinx::LinkContext::FunctionMask) != 0
+    if ((linkContext->type & QtXmlToSphinxLink::FunctionMask) != 0
         && (linkContext->linkRef + QLatin1String("()")) == linktext) {
         return QString();
     }
     return  linktext;
 }
 
-void QtXmlToSphinx::handleLinkText(LinkContext *linkContext, const QString &linktext)
+void QtXmlToSphinx::handleLinkText(QtXmlToSphinxLink *linkContext, const QString &linktext)
 {
     linkContext->linkText = fixLinkText(linkContext, linktext);
 }
 
-void QtXmlToSphinx::handleLinkEnd(LinkContext *linkContext)
+void QtXmlToSphinx::handleLinkEnd(QtXmlToSphinxLink *linkContext)
 {
-    m_output << *linkContext;
+    m_output << m_generator->resolveLink(*linkContext);
 }
 
 WebXmlTag QtXmlToSphinx::parentTag() const
diff --git a/sources/shiboken6/generator/qtdoc/qtxmltosphinx.h b/sources/shiboken6/generator/qtdoc/qtxmltosphinx.h
index cb6bb504a..55d6a79b1 100644
--- a/sources/shiboken6/generator/qtdoc/qtxmltosphinx.h
+++ b/sources/shiboken6/generator/qtdoc/qtxmltosphinx.h
@@ -39,11 +39,13 @@
 #include <QtCore/QTextStream>
 
 QT_BEGIN_NAMESPACE
+class QDebug;
 class QXmlStreamReader;
 QT_END_NAMESPACE
 
 class QtXmlToSphinxDocGeneratorInterface;
 struct QtXmlToSphinxParameters;
+struct QtXmlToSphinxLink;
 
 enum class WebXmlTag;
 
@@ -52,8 +54,6 @@ class QtXmlToSphinx
 public:
     Q_DISABLE_COPY_MOVE(QtXmlToSphinx)
 
-    struct LinkContext;
-
     struct InlineImage
     {
         QString tag;
@@ -168,9 +168,9 @@ private:
     void handleAnchorTag(QXmlStreamReader& reader);
     void handleRstPassTroughTag(QXmlStreamReader& reader);
 
-    LinkContext *handleLinkStart(const QString &type, QString ref) const;
-    static void handleLinkText(LinkContext *linkContext, const QString &linktext) ;
-    void handleLinkEnd(LinkContext *linkContext);
+    QtXmlToSphinxLink *handleLinkStart(const QString &type, QString ref) const;
+    static void handleLinkText(QtXmlToSphinxLink *linkContext, const QString &linktext) ;
+    void handleLinkEnd(QtXmlToSphinxLink *linkContext);
     WebXmlTag parentTag() const;
 
     void warn(const QString &message) const;
@@ -183,8 +183,8 @@ private:
     QStack<StringSharedPtr> m_buffers; // Maintain address stability since it used in TextStream
 
     Table m_currentTable;
-    QScopedPointer<LinkContext> m_linkContext; // for <link>
-    QScopedPointer<LinkContext> m_seeAlsoContext; // for <see-also>foo()</see-also>
+    QScopedPointer<QtXmlToSphinxLink> m_linkContext; // for <link>
+    QScopedPointer<QtXmlToSphinxLink> m_seeAlsoContext; // for <see-also>foo()</see-also>
     bool m_tableHasHeader = false;
     QString m_context;
     const QtXmlToSphinxDocGeneratorInterface *m_generator;
@@ -212,4 +212,6 @@ inline TextStream& operator<<(TextStream& s, const QtXmlToSphinx& xmlToSphinx)
     return s << xmlToSphinx.result();
 }
 
+QDebug operator<<(QDebug d, const QtXmlToSphinxLink &l);
+
 #endif // QTXMLTOSPHINX_H
diff --git a/sources/shiboken6/generator/qtdoc/qtxmltosphinxinterface.h b/sources/shiboken6/generator/qtdoc/qtxmltosphinxinterface.h
index c4bdedd21..d4e792d76 100644
--- a/sources/shiboken6/generator/qtdoc/qtxmltosphinxinterface.h
+++ b/sources/shiboken6/generator/qtdoc/qtxmltosphinxinterface.h
@@ -43,6 +43,26 @@ struct QtXmlToSphinxParameters
     bool snippetComparison = false;
 };
 
+struct QtXmlToSphinxLink
+{
+    enum Type
+    {
+        Method = 0x1, Function = 0x2,
+        FunctionMask = Method | Function,
+        Class = 0x4, Attribute = 0x8, Module = 0x10,
+        Reference = 0x20, External= 0x40
+    };
+
+    enum Flags { InsideBold = 0x1, InsideItalic = 0x2 };
+
+    explicit QtXmlToSphinxLink(const QString &ref) : linkRef(ref) {}
+
+    QString linkRef;
+    QString linkText;
+    Type type = Reference;
+    int flags = 0;
+};
+
 class QtXmlToSphinxDocGeneratorInterface
 {
 public:
@@ -54,6 +74,8 @@ public:
 
     virtual const QLoggingCategory &loggingCategory() const = 0;
 
+    virtual QtXmlToSphinxLink resolveLink(const QtXmlToSphinxLink &) const = 0;
+
     virtual ~QtXmlToSphinxDocGeneratorInterface() = default;
 };
 
diff --git a/sources/shiboken6/tests/qtxmltosphinxtest/qtxmltosphinxtest.cpp b/sources/shiboken6/tests/qtxmltosphinxtest/qtxmltosphinxtest.cpp
index c9aebc443..ea60d36b5 100644
--- a/sources/shiboken6/tests/qtxmltosphinxtest/qtxmltosphinxtest.cpp
+++ b/sources/shiboken6/tests/qtxmltosphinxtest/qtxmltosphinxtest.cpp
@@ -56,6 +56,11 @@ const QLoggingCategory &QtXmlToSphinxTest::loggingCategory() const
     return lcQtXmlToSphinxTest();
 }
 
+QtXmlToSphinxLink QtXmlToSphinxTest::resolveLink(const QtXmlToSphinxLink &link) const
+{
+    return link;
+}
+
 QString QtXmlToSphinxTest::transformXml(const QString &xml) const
 {
     return QtXmlToSphinx(this, m_parameters, xml).result();
diff --git a/sources/shiboken6/tests/qtxmltosphinxtest/qtxmltosphinxtest.h b/sources/shiboken6/tests/qtxmltosphinxtest/qtxmltosphinxtest.h
index dffbd86c0..8f74baaf5 100644
--- a/sources/shiboken6/tests/qtxmltosphinxtest/qtxmltosphinxtest.h
+++ b/sources/shiboken6/tests/qtxmltosphinxtest/qtxmltosphinxtest.h
@@ -43,6 +43,7 @@ public:
     QString resolveContextForMethod(const QString &,
                                     const QString &) const override;
     const QLoggingCategory &loggingCategory() const override;
+    QtXmlToSphinxLink resolveLink(const QtXmlToSphinxLink &link) const override;
 
 private slots:
     void testTable_data();