1 /**************************************************************************** 2 ** 3 ** Copyright (C) 2019 The Qt Company Ltd. 4 ** Contact: https://www.qt.io/licensing/ 5 ** 6 ** This file is part of the tools applications of the Qt Toolkit. 7 ** 8 ** $QT_BEGIN_LICENSE:GPL-EXCEPT$ 9 ** Commercial License Usage 10 ** Licensees holding valid commercial Qt licenses may use this file in 11 ** accordance with the commercial license agreement provided with the 12 ** Software or, alternatively, in accordance with the terms contained in 13 ** a written agreement between you and The Qt Company. For licensing terms 14 ** and conditions see https://www.qt.io/terms-conditions. For further 15 ** information use the contact form at https://www.qt.io/contact-us. 16 ** 17 ** GNU General Public License Usage 18 ** Alternatively, this file may be used under the terms of the GNU 19 ** General Public License version 3 as published by the Free Software 20 ** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT 21 ** included in the packaging of this file. Please review the following 22 ** information to ensure the GNU General Public License requirements will 23 ** be met: https://www.gnu.org/licenses/gpl-3.0.html. 24 ** 25 ** $QT_END_LICENSE$ 26 ** 27 ****************************************************************************/ 28 29 #ifndef GENERATOR_H 30 #define GENERATOR_H 31 32 #include "text.h" 33 34 #include <QtCore/qlist.h> 35 #include <QtCore/qmap.h> 36 #include <QtCore/qstring.h> 37 #include <QtCore/qstringlist.h> 38 #include <QtCore/qtextstream.h> 39 40 QT_BEGIN_NAMESPACE 41 42 typedef QMultiMap<QString, Node *> NodeMultiMap; 43 typedef QMap<Node *, NodeMultiMap> ParentMaps; 44 45 class CodeMarker; 46 class Location; 47 class Node; 48 class QDocDatabase; 49 50 class Generator 51 { 52 Q_DECLARE_TR_FUNCTIONS(QDoc::Generator) 53 54 public: 55 enum ListType { Generic, Obsolete }; 56 enum Addendum { Invokable, PrivateSignal, QmlSignalHandler, AssociatedProperties, TypeAlias }; 57 58 Generator(); 59 virtual ~Generator(); 60 canHandleFormat(const QString & format)61 virtual bool canHandleFormat(const QString &format) { return format == this->format(); } 62 virtual QString format() = 0; 63 virtual void generateDocs(); 64 virtual void initializeGenerator(); 65 virtual void initializeFormat(); 66 virtual void terminateGenerator(); 67 virtual QString typeString(const Node *node); 68 69 QString fullDocumentLocation(const Node *node, bool useSubdir = false); 70 QString linkForExampleFile(const QString &path, const Node *parent, 71 const QString &fileExt = QString()); 72 static QString exampleFileTitle(const ExampleNode *relative, const QString &fileName); currentGenerator()73 static Generator *currentGenerator() { return currentGenerator_; } 74 static Generator *generatorForFormat(const QString &format); 75 static void initialize(); outputDir()76 static const QString &outputDir() { return outDir_; } outputSubdir()77 static const QString &outputSubdir() { return outSubdir_; } 78 static void terminate(); outputFileNames()79 static const QStringList &outputFileNames() { return outFileNames_; } 80 static void writeOutFileNames(); 81 static void augmentImageDirs(QSet<QString> &moreImageDirs); noLinkErrors()82 static bool noLinkErrors() { return noLinkErrors_; } autolinkErrors()83 static bool autolinkErrors() { return autolinkErrors_; } defaultModuleName()84 static QString defaultModuleName() { return project_; } resetUseOutputSubdirs()85 static void resetUseOutputSubdirs() { useOutputSubdirs_ = false; } useOutputSubdirs()86 static bool useOutputSubdirs() { return useOutputSubdirs_; } setQmlTypeContext(QmlTypeNode * t)87 static void setQmlTypeContext(QmlTypeNode *t) { qmlTypeContext_ = t; } qmlTypeContext()88 static QmlTypeNode *qmlTypeContext() { return qmlTypeContext_; } 89 static QString cleanRef(const QString &ref); 90 static QString plainCode(const QString &markedCode); 91 92 protected: 93 static QFile *openSubPageFile(const Node *node, const QString &fileName); 94 void beginFilePage(const Node *node, const QString &fileName); endFilePage()95 void endFilePage() { endSubPage(); } // for symmetry 96 void beginSubPage(const Node *node, const QString &fileName); 97 void endSubPage(); 98 virtual QString fileBase(const Node *node) const; 99 virtual QString fileExtension() const = 0; generateQAPage()100 virtual void generateQAPage() {} generateExampleFilePage(const Node *,const QString &,CodeMarker *)101 virtual void generateExampleFilePage(const Node *, const QString &, CodeMarker *) {} 102 virtual void generateAlsoList(const Node *node, CodeMarker *marker); generateAtom(const Atom *,const Node *,CodeMarker *)103 virtual int generateAtom(const Atom *, const Node *, CodeMarker *) { return 0; } 104 virtual void generateBody(const Node *node, CodeMarker *marker); generateCppReferencePage(Aggregate *,CodeMarker *)105 virtual void generateCppReferencePage(Aggregate *, CodeMarker *) {} generateProxyPage(Aggregate *,CodeMarker *)106 virtual void generateProxyPage(Aggregate *, CodeMarker *) {} generateQmlTypePage(QmlTypeNode *,CodeMarker *)107 virtual void generateQmlTypePage(QmlTypeNode *, CodeMarker *) {} generateQmlBasicTypePage(QmlBasicTypeNode *,CodeMarker *)108 virtual void generateQmlBasicTypePage(QmlBasicTypeNode *, CodeMarker *) {} generatePageNode(PageNode *,CodeMarker *)109 virtual void generatePageNode(PageNode *, CodeMarker *) {} generateCollectionNode(CollectionNode *,CodeMarker *)110 virtual void generateCollectionNode(CollectionNode *, CodeMarker *) {} generateGenericCollectionPage(CollectionNode *,CodeMarker *)111 virtual void generateGenericCollectionPage(CollectionNode *, CodeMarker *) {} 112 virtual void generateInheritedBy(const ClassNode *classe, CodeMarker *marker); 113 virtual void generateInherits(const ClassNode *classe, CodeMarker *marker); 114 virtual void generateDocumentation(Node *node); 115 virtual void generateMaintainerList(const Aggregate *node, CodeMarker *marker); 116 virtual void generateQmlInheritedBy(const QmlTypeNode *qcn, CodeMarker *marker); generateQmlInherits(QmlTypeNode *,CodeMarker *)117 virtual void generateQmlInherits(QmlTypeNode *, CodeMarker *) {} 118 virtual bool generateQmlText(const Text &text, const Node *relative, CodeMarker *marker, 119 const QString &qmlName); 120 virtual bool generateText(const Text &text, const Node *relative, CodeMarker *marker); 121 virtual QString imageFileName(const Node *relative, const QString &fileBase); 122 virtual int skipAtoms(const Atom *atom, Atom::AtomType type) const; 123 124 static bool matchAhead(const Atom *atom, Atom::AtomType expectedAtomType); 125 static QString outputPrefix(const Node *node); 126 static QString outputSuffix(const Node *node); 127 static void singularPlural(Text &text, const NodeList &nodes); 128 static void supplementAlsoList(const Node *node, QVector<Text> &alsoList); 129 static QString trimmedTrailing(const QString &string, const QString &prefix, 130 const QString &suffix); 131 void initializeTextOutput(); 132 QString fileName(const Node *node, const QString &extension = QString()) const; 133 QMap<QString, QString> &formattingLeftMap(); 134 QMap<QString, QString> &formattingRightMap(); 135 const Atom *generateAtomList(const Atom *atom, const Node *relative, CodeMarker *marker, 136 bool generate, int &numGeneratedAtoms); 137 void generateRequiredLinks(const Node *node, CodeMarker *marker); 138 void generateLinkToExample(const ExampleNode *en, CodeMarker *marker, 139 const QString &exampleUrl); 140 virtual void generateFileList(const ExampleNode *en, CodeMarker *marker, bool images); 141 static QString formatSince(const Node *node); 142 void generateSince(const Node *node, CodeMarker *marker); 143 void generateStatus(const Node *node, CodeMarker *marker); 144 virtual void generateAddendum(const Node *node, Addendum type, CodeMarker *marker, 145 bool generateNote = true); 146 void generateThreadSafeness(const Node *node, CodeMarker *marker); 147 QString getMetadataElement(const Aggregate *inner, const QString &t); 148 QStringList getMetadataElements(const Aggregate *inner, const QString &t); 149 void generateOverloadedSignal(const Node *node, CodeMarker *marker); 150 static QString getOverloadedSignalCode(const Node *node); 151 QString indent(int level, const QString &markedCode); 152 QTextStream &out(); 153 QString outFileName(); 154 bool parseArg(const QString &src, const QString &tag, int *pos, int n, QStringRef *contents, 155 QStringRef *par1 = nullptr, bool debug = false); 156 void setImageFileExtensions(const QStringList &extensions); 157 void unknownAtom(const Atom *atom); 158 int appendSortedQmlNames(Text &text, const Node *base, const NodeList &subs); 159 160 static bool hasExceptions(const Node *node, NodeList &reentrant, NodeList &threadsafe, 161 NodeList &nonreentrant); 162 163 QString naturalLanguage; 164 #ifndef QT_NO_TEXTCODEC 165 QTextCodec *outputCodec; 166 QString outputEncoding; 167 #endif 168 QString tagFile_; 169 QStack<QTextStream *> outStreamStack; 170 171 void appendFullName(Text &text, const Node *apparentNode, const Node *relative, 172 const Node *actualNode = nullptr); 173 void appendFullName(Text &text, const Node *apparentNode, const QString &fullName, 174 const Node *actualNode); 175 void appendFullNames(Text &text, const NodeList &nodes, const Node *relative); 176 int appendSortedNames(Text &text, const ClassNode *classe, 177 const QVector<RelatedClass> &classes); 178 void appendSignature(Text &text, const Node *node); 179 void signatureList(const NodeList &nodes, const Node *relative, CodeMarker *marker); 180 181 void addImageToCopy(const ExampleNode *en, const QString &file); compareNodes(const Node * a,const Node * b)182 static bool compareNodes(const Node *a, const Node *b) { return (a->name() < b->name()); } comparePaths(const QString & a,const QString & b)183 static bool comparePaths(const QString &a, const QString &b) { return (a < b); } 184 185 private: 186 static Generator *currentGenerator_; 187 static QStringList exampleDirs; 188 static QStringList exampleImgExts; 189 static QMap<QString, QMap<QString, QString>> fmtLeftMaps; 190 static QMap<QString, QMap<QString, QString>> fmtRightMaps; 191 static QVector<Generator *> generators; 192 static QStringList imageDirs; 193 static QStringList imageFiles; 194 static QMap<QString, QStringList> imgFileExts; 195 static QString project_; 196 static QString outDir_; 197 static QString outSubdir_; 198 static QStringList outFileNames_; 199 static QSet<QString> outputFormats; 200 static QHash<QString, QString> outputPrefixes; 201 static QHash<QString, QString> outputSuffixes; 202 static QStringList scriptDirs; 203 static QStringList scriptFiles; 204 static QStringList styleDirs; 205 static QStringList styleFiles; 206 static bool noLinkErrors_; 207 static bool autolinkErrors_; 208 static bool redirectDocumentationToDevNull_; 209 static bool qdocSingleExec_; 210 static bool useOutputSubdirs_; 211 static QmlTypeNode *qmlTypeContext_; 212 213 void generateReimplementsClause(const FunctionNode *fn, CodeMarker *marker); 214 static void copyTemplateFiles(const QString &configVar, const QString &subDir); 215 216 protected: 217 QDocDatabase *qdb_; 218 bool inLink_; 219 bool inContents_; 220 bool inSectionHeading_; 221 bool inTableHeader_; 222 bool threeColumnEnumValueTable_; 223 bool showInternal_; 224 bool singleExec_; 225 bool quoting_; 226 int numTableRows_; 227 QString link_; 228 QString sectionNumber_; 229 }; 230 231 QT_END_NAMESPACE 232 233 #endif 234