Documentation extraction: Add error handling

Trim the strings returned by the XPath queries and warn about
failing queries.

Task-number: PYSIDE-363
Change-Id: Ia0233d490497597cb78aa16b0908fe226270705c
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>

6 files changed, 100 insertions, 13 deletions

diff --git a/sources/shiboken2/ApiExtractor/abstractmetalang.h b/sources/shiboken2/ApiExtractor/abstractmetalang.h
index 83c1c334f..ca64011bf 100644
--- a/sources/shiboken2/ApiExtractor/abstractmetalang.h
+++ b/sources/shiboken2/ApiExtractor/abstractmetalang.h
@@ -74,7 +74,9 @@ public:
     Documentation() {}
 
     Documentation(const QString& value, Format fmt = Documentation::Native)
-            : m_data(value), m_format(fmt) {}
+            : m_data(value.trimmed()), m_format(fmt) {}
+
+    bool isEmpty() const { return m_data.isEmpty(); }
 
     QString value() const
     {
@@ -83,7 +85,8 @@ public:
 
     void setValue(const QString& value, Format fmt = Documentation::Native)
     {
-        m_data = value; m_format = fmt;
+        m_data = value.trimmed();
+        m_format = fmt;
     }
 
     Documentation::Format format() const
diff --git a/sources/shiboken2/ApiExtractor/docparser.cpp b/sources/shiboken2/ApiExtractor/docparser.cpp
index 50a08d7c9..1d1783f05 100644
--- a/sources/shiboken2/ApiExtractor/docparser.cpp
+++ b/sources/shiboken2/ApiExtractor/docparser.cpp
@@ -29,6 +29,8 @@
 #include "abstractmetalang.h"
 #include "typesystem.h"
 #include <QtCore/QDebug>
+#include <QtCore/QDir>
+#include <QtCore/QTextStream>
 #include <QtXmlPatterns/QXmlQuery>
 #include <QBuffer>
 
@@ -49,7 +51,7 @@ QString DocParser::getDocumentation(QXmlQuery& xquery, const QString& query,
                                     const DocModificationList& mods) const
 {
     QString doc = execXQuery(xquery, query);
-    return applyDocModifications(mods, doc);
+    return applyDocModifications(mods, doc.trimmed());
 }
 
 QString DocParser::execXQuery(QXmlQuery& xquery, const QString& query) const
@@ -99,6 +101,47 @@ AbstractMetaFunctionList DocParser::documentableFunctions(const AbstractMetaClas
     return result;
 }
 
+QString DocParser::msgCannotFindDocumentation(const QString &fileName,
+                                          const char *what, const QString &name,
+                                          const QString &query)
+{
+    QString result;
+    QTextStream(&result) << "Cannot find documentation for " << what
+        << ' ' << name << " in:\n    " << QDir::toNativeSeparators(fileName)
+        << "\n  using query:\n    " << query;
+    return result;
+}
+
+QString DocParser::msgCannotFindDocumentation(const QString &fileName,
+                                              const AbstractMetaClass *metaClass,
+                                              const AbstractMetaFunction *function,
+                                              const QString &query)
+{
+    return msgCannotFindDocumentation(fileName, "function",
+                                      metaClass->name() + QLatin1String("::") + function->name() + QLatin1String("()"),
+                                      query);
+}
+
+QString DocParser::msgCannotFindDocumentation(const QString &fileName,
+                                              const AbstractMetaClass *metaClass,
+                                              const AbstractMetaEnum *e,
+                                              const QString &query)
+{
+    return msgCannotFindDocumentation(fileName, "enum",
+                                      metaClass->name() + QLatin1String("::") + e->name(),
+                                      query);
+}
+
+QString DocParser::msgCannotFindDocumentation(const QString &fileName,
+                                              const AbstractMetaClass *metaClass,
+                                              const AbstractMetaField *f,
+                                              const QString &query)
+{
+    return msgCannotFindDocumentation(fileName, "field",
+                                      metaClass->name() + QLatin1String("::") + f->name(),
+                                      query);
+}
+
 namespace
 {
 
@@ -130,7 +173,7 @@ struct XslResources
 
 QString DocParser::applyDocModifications(const DocModificationList& mods, const QString& xml) const
 {
-    if (mods.isEmpty())
+    if (mods.isEmpty() || xml.isEmpty())
         return xml;
 
     bool hasXPathBasedModification = false;
@@ -199,6 +242,6 @@ QString DocParser::applyDocModifications(const DocModificationList& mods, const
     }
 
     Q_ASSERT(result != xml);
-    return result;
+    return result.trimmed();
 }
 
diff --git a/sources/shiboken2/ApiExtractor/docparser.h b/sources/shiboken2/ApiExtractor/docparser.h
index afca254a4..1770815b0 100644
--- a/sources/shiboken2/ApiExtractor/docparser.h
+++ b/sources/shiboken2/ApiExtractor/docparser.h
@@ -120,6 +120,22 @@ protected:
 
     static AbstractMetaFunctionList documentableFunctions(const AbstractMetaClass *metaClass);
 
+    static QString msgCannotFindDocumentation(const QString &fileName,
+                                              const char *what, const QString &name,
+                                              const QString &query);
+    static QString msgCannotFindDocumentation(const QString &fileName,
+                                              const AbstractMetaClass *metaClass,
+                                              const AbstractMetaFunction *function,
+                                              const QString &query);
+    static QString msgCannotFindDocumentation(const QString &fileName,
+                                              const AbstractMetaClass *metaClass,
+                                              const AbstractMetaEnum *e,
+                                              const QString &query);
+    static QString msgCannotFindDocumentation(const QString &fileName,
+                                              const AbstractMetaClass *metaClass,
+                                              const AbstractMetaField *f,
+                                              const QString &query);
+
 private:
     QString m_packageName;
     QString m_docDataDir;
diff --git a/sources/shiboken2/ApiExtractor/doxygenparser.cpp b/sources/shiboken2/ApiExtractor/doxygenparser.cpp
index 0361445fd..1cffa3b67 100644
--- a/sources/shiboken2/ApiExtractor/doxygenparser.cpp
+++ b/sources/shiboken2/ApiExtractor/doxygenparser.cpp
@@ -96,12 +96,11 @@ void DoxygenParser::fillDocumentation(AbstractMetaClass* metaClass)
     xquery.setFocus(QUrl(doxyFilePath));
 
     // Get class documentation
-    QString classDoc = getDocumentation(xquery, QLatin1String("/doxygen/compounddef/detaileddescription"),
+    const QString classQuery = QLatin1String("/doxygen/compounddef/detaileddescription");
+    QString classDoc = getDocumentation(xquery, classQuery,
                                         metaClass->typeEntry()->docModifications());
-    if (classDoc.isEmpty()) {
-        qCWarning(lcShiboken).noquote().nospace()
-            << "Can't find documentation for class \"" << metaClass->name() << "\".";
-    }
+    if (classDoc.isEmpty())
+        qCWarning(lcShiboken(), "%s", qPrintable(msgCannotFindDocumentation(doxyFilePath, "class", metaClass->name(), classQuery)));
     metaClass->setDocumentation(classDoc);
 
     //Functions Documentation
@@ -147,6 +146,10 @@ void DoxygenParser::fillDocumentation(AbstractMetaClass* metaClass)
             query += QLatin1String("/../detaileddescription)[1]");
         }
         QString doc = getDocumentation(xquery, query, DocModificationList());
+        if (doc.isEmpty()) {
+            qCWarning(lcShiboken(), "%s",
+                      qPrintable(msgCannotFindDocumentation(doxyFilePath, metaClass, func, query)));
+        }
         func->setDocumentation(doc);
         isProperty = false;
     }
@@ -160,6 +163,10 @@ void DoxygenParser::fillDocumentation(AbstractMetaClass* metaClass)
         QString query = QLatin1String("/doxygen/compounddef/sectiondef/memberdef/name[text()=\"")
                         + field->name() + QLatin1String("\"]/../detaileddescription");
         QString doc = getDocumentation(xquery, query, DocModificationList());
+        if (doc.isEmpty()) {
+            qCWarning(lcShiboken(), "%s",
+                      qPrintable(msgCannotFindDocumentation(doxyFilePath, metaClass, field, query)));
+        }
         field->setDocumentation(doc);
     }
 
@@ -169,6 +176,10 @@ void DoxygenParser::fillDocumentation(AbstractMetaClass* metaClass)
         QString query = QLatin1String("/doxygen/compounddef/sectiondef/memberdef[@kind=\"enum\"]/name[text()=\"")
             + meta_enum->name() + QLatin1String("\"]/..");
         QString doc = getDocumentation(xquery, query, DocModificationList());
+        if (doc.isEmpty()) {
+            qCWarning(lcShiboken(), "%s",
+                      qPrintable(msgCannotFindDocumentation(doxyFilePath, metaClass, meta_enum, query)));
+        }
         meta_enum->setDocumentation(doc);
     }
 
diff --git a/sources/shiboken2/ApiExtractor/qtdocparser.cpp b/sources/shiboken2/ApiExtractor/qtdocparser.cpp
index b8a718ddc..508faa6dc 100644
--- a/sources/shiboken2/ApiExtractor/qtdocparser.cpp
+++ b/sources/shiboken2/ApiExtractor/qtdocparser.cpp
@@ -68,7 +68,8 @@ void QtDocParser::fillDocumentation(AbstractMetaClass* metaClass)
     }
 
     QXmlQuery xquery;
-    xquery.setFocus(QUrl::fromLocalFile(sourceFile.absoluteFilePath()));
+    const QString sourceFileName = sourceFile.absoluteFilePath();
+    xquery.setFocus(QUrl::fromLocalFile(sourceFileName));
 
     QString className = metaClass->name();
 
@@ -87,6 +88,8 @@ void QtDocParser::fillDocumentation(AbstractMetaClass* metaClass)
     }
 
     Documentation doc(getDocumentation(xquery, query, classModifs));
+    if (doc.isEmpty())
+         qCWarning(lcShiboken(), "%s", qPrintable(msgCannotFindDocumentation(sourceFileName, "class", className, query)));
     metaClass->setDocumentation(doc);
 
 
@@ -134,6 +137,10 @@ void QtDocParser::fillDocumentation(AbstractMetaClass* metaClass)
                 funcModifs.append(funcModif);
         }
         doc.setValue(getDocumentation(xquery, query, funcModifs));
+        if (doc.isEmpty()) {
+            qCWarning(lcShiboken(), "%s",
+                      qPrintable(msgCannotFindDocumentation(sourceFileName, metaClass, func, query)));
+        }
         func->setDocumentation(doc);
     }
 #if 0
@@ -156,6 +163,10 @@ void QtDocParser::fillDocumentation(AbstractMetaClass* metaClass)
                         + className + QLatin1String("\"]/enum[@name=\"")
                         + meta_enum->name() + QLatin1String("\"]/description");
         doc.setValue(getDocumentation(xquery, query, DocModificationList()));
+        if (doc.isEmpty()) {
+            qCWarning(lcShiboken(), "%s",
+                      qPrintable(msgCannotFindDocumentation(sourceFileName, metaClass, meta_enum, query)));
+        }
         meta_enum->setDocumentation(doc);
     }
 }
@@ -184,5 +195,8 @@ Documentation QtDocParser::retrieveModuleDocumentation(const QString& name)
 
     // Module documentation
     QString query = QLatin1String("/WebXML/document/page[@name=\"") + moduleName + QLatin1String("\"]/description");
-    return Documentation(getDocumentation(xquery, query, DocModificationList()));
+    const Documentation doc = getDocumentation(xquery, query, DocModificationList());
+    if (doc.isEmpty())
+        qCWarning(lcShiboken(), "%s", qPrintable(msgCannotFindDocumentation(sourceFile, "module", name, query)));
+    return doc;
 }
diff --git a/sources/shiboken2/ApiExtractor/tests/testmodifydocumentation.cpp b/sources/shiboken2/ApiExtractor/tests/testmodifydocumentation.cpp
index 96bd0251b..d56186479 100644
--- a/sources/shiboken2/ApiExtractor/tests/testmodifydocumentation.cpp
+++ b/sources/shiboken2/ApiExtractor/tests/testmodifydocumentation.cpp
@@ -66,7 +66,7 @@ void TestModifyDocumentation::testModifyDocumentation()
                 <para>Paragraph number 1</para>\n\
     <para>Paragraph number 2</para>\n\
     <para>Some changed contents here</para>\n\
-</description>\n"));
+</description>"));
 }
 
 // We expand QTEST_MAIN macro but using QCoreApplication instead of QApplication