diff options
| author | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2021-12-13 14:24:42 +0100 |
|---|---|---|
| committer | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2021-12-16 15:38:09 +0100 |
| commit | b00c9f19ff37f2fed57c780660001f5c1a25a5cb (patch) | |
| tree | ed167eb1cd1ff9480c477aa166814565078e2475 /sources/shiboken6/ApiExtractor/classdocumentation.h | |
| parent | 565ce8c4f32822034ffe9ff25d4093c7401d2e6a (diff) | |
shiboken6/Documentation: Replace XPath/Xquery usage for retrieving WebXML docs by a parser
shiboken used XPath expressions to extract the function descriptions
from the qdoc-generated WebXML. With the deprecation of QtXmlPatterns
in Qt 6, libxml/xslt was used for this. A major drawback is that
libxml/xslt is unable to match entities in attributes which means
functions taking parameters by const-ref could not be found. This
required cumbersome workarounds involving repeated searches, which
still were not sufficient to find all functions.
To fix this, write a WebXML parser based on QXmlStreamReader
that extracts the contents of a WebXML page into some simple
data structures and use those for searching.
On this occasion, also use the metafunction flags to correctly
match binary operator functions.
This reduces the number of functions for which no documentation
can be found (from ~1100 to ~800 for the qtbase repository).
From the remaining functions, ~230 are functions inherited from
templates, which should at least be listed. Others are caused
by qdoc not finding hidden friends.
The remaining usages of libxml/xslt are the doxygen parser and the
documentation modifications using XSLT.
Task-number: PYSIDE-1106
Change-Id: I31c045ad42948afad884f40d5bbc8bee7555859e
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Diffstat (limited to 'sources/shiboken6/ApiExtractor/classdocumentation.h')
| -rw-r--r-- | sources/shiboken6/ApiExtractor/classdocumentation.h | 100 |
1 files changed, 100 insertions, 0 deletions
diff --git a/sources/shiboken6/ApiExtractor/classdocumentation.h b/sources/shiboken6/ApiExtractor/classdocumentation.h new file mode 100644 index 000000000..5b202bbc3 --- /dev/null +++ b/sources/shiboken6/ApiExtractor/classdocumentation.h @@ -0,0 +1,100 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qt for Python. +** +** $QT_BEGIN_LICENSE:GPL-EXCEPT$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3 as published by the Free Software +** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef CLASSDOCUMENTATION_H +#define CLASSDOCUMENTATION_H + +#include <QtCore/QStringList> + +QT_FORWARD_DECLARE_CLASS(QDebug) + +/// An enumeration in a WebXML/doxygen document +struct EnumDocumentation +{ + QString name; + QString description; +}; + +/// A QObject property in a WebXML/doxygen document +struct PropertyDocumentation +{ + QString name; + QString description; +}; + +/// Helper struct for querying a function in a WebXML/doxygen document +struct FunctionDocumentationQuery +{ + QString name; + QStringList parameters; + bool constant = false; +}; + +/// A function in a WebXML/doxygen document +struct FunctionDocumentation : public FunctionDocumentationQuery +{ + QString signature; + QString returnType; + QString description; +}; + +using FunctionDocumentationList = QList<FunctionDocumentation>; + +/// A class/namespace in a WebXML/doxygen document +struct ClassDocumentation +{ + qsizetype indexOfEnum(const QString &name) const; + FunctionDocumentationList findFunctionCandidates(const QString &name, + bool constant) const; + static qsizetype indexOfFunction(const FunctionDocumentationList &fl, + const FunctionDocumentationQuery &q); + qsizetype indexOfProperty(const QString &name) const; + + QString name; + QString description; + + QList<EnumDocumentation> enums; + QList<PropertyDocumentation> properties; + FunctionDocumentationList functions; + + operator bool() const { return !name.isEmpty(); } +}; + +/// Parse a WebXML class/namespace document +ClassDocumentation parseWebXml(const QString &fileName, QString *errorMessage); + +/// Extract the module description from a WebXML module document +QString webXmlModuleDescription(const QString &fileName, QString *errorMessage); + +QDebug operator<<(QDebug debug, const EnumDocumentation &e); +QDebug operator<<(QDebug debug, const PropertyDocumentation &p); +QDebug operator<<(QDebug debug, const FunctionDocumentationQuery &q); +QDebug operator<<(QDebug debug, const FunctionDocumentation &f); +QDebug operator<<(QDebug debug, const ClassDocumentation &c); + +#endif // CLASSDOCUMENTATION_H |