1// Copyright (C) 2019 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
3
4#include "qdoccommandlineparser.h"
5
6#include "utilities.h"
7
8#include <QtCore/qdebug.h>
9#include <QtCore/qfile.h>
10
11QDocCommandLineParser::QDocCommandLineParser()
12 : QCommandLineParser(),
13 defineOption(QStringList() << QStringLiteral("D")),
14 dependsOption(QStringList() << QStringLiteral("depends")),
15 highlightingOption(QStringList() << QStringLiteral("highlighting")),
16 showInternalOption(QStringList() << QStringLiteral("showinternal")),
17 redirectDocumentationToDevNullOption(QStringList()
18 << QStringLiteral("redirect-documentation-to-dev-null")),
19 noExamplesOption(QStringList() << QStringLiteral("no-examples")),
20 indexDirOption(QStringList() << QStringLiteral("indexdir")),
21 installDirOption(QStringList() << QStringLiteral("installdir")),
22 outputDirOption(QStringList() << QStringLiteral("outputdir")),
23 outputFormatOption(QStringList() << QStringLiteral("outputformat")),
24 noLinkErrorsOption(QStringList() << QStringLiteral("no-link-errors")),
25 autoLinkErrorsOption(QStringList() << QStringLiteral("autolink-errors")),
26 debugOption(QStringList() << QStringLiteral("debug")),
27 atomsDumpOption("atoms-dump"),
28 prepareOption(QStringList() << QStringLiteral("prepare")),
29 generateOption(QStringList() << QStringLiteral("generate")),
30 logProgressOption(QStringList() << QStringLiteral("log-progress")),
31 singleExecOption(QStringList() << QStringLiteral("single-exec")),
32 includePathOption("I", "Add dir to the include path for header files.", "path"),
33 includePathSystemOption("isystem", "Add dir to the system include path for header files.",
34 "path"),
35 frameworkOption("F", "Add macOS framework to the include path for header files.",
36 "framework"),
37 timestampsOption(QStringList() << QStringLiteral("timestamps")),
38 useDocBookExtensions(QStringList() << QStringLiteral("docbook-extensions"))
39{
40 setApplicationDescription(QStringLiteral("Qt documentation generator"));
41 addHelpOption();
42 addVersionOption();
43
44 setSingleDashWordOptionMode(QCommandLineParser::ParseAsLongOptions);
45
46 addPositionalArgument(name: "file1.qdocconf ...", QStringLiteral("Input files"));
47
48 defineOption.setDescription(
49 QStringLiteral("Define the argument as a macro while parsing sources"));
50 defineOption.setValueName(QStringLiteral("macro[=def]"));
51 defineOption.setFlags(QCommandLineOption::ShortOptionStyle);
52 addOption(commandLineOption: defineOption);
53
54 dependsOption.setDescription(QStringLiteral("Specify dependent modules"));
55 dependsOption.setValueName(QStringLiteral("module"));
56 addOption(commandLineOption: dependsOption);
57
58 highlightingOption.setDescription(
59 QStringLiteral("Turn on syntax highlighting (makes qdoc run slower)"));
60 addOption(commandLineOption: highlightingOption);
61
62 showInternalOption.setDescription(QStringLiteral("Include content marked internal"));
63 addOption(commandLineOption: showInternalOption);
64
65 redirectDocumentationToDevNullOption.setDescription(
66 QStringLiteral("Save all documentation content to /dev/null. "
67 " Useful if someone is interested in qdoc errors only."));
68 addOption(commandLineOption: redirectDocumentationToDevNullOption);
69
70 noExamplesOption.setDescription(QStringLiteral("Do not generate documentation for examples"));
71 addOption(commandLineOption: noExamplesOption);
72
73 indexDirOption.setDescription(
74 QStringLiteral("Specify a directory where QDoc should search for index files to load"));
75 indexDirOption.setValueName(QStringLiteral("dir"));
76 addOption(commandLineOption: indexDirOption);
77
78 installDirOption.setDescription(QStringLiteral(
79 "Specify the directory where the output will be after running \"make install\""));
80 installDirOption.setValueName(QStringLiteral("dir"));
81 addOption(commandLineOption: installDirOption);
82
83 outputDirOption.setDescription(
84 QStringLiteral("Specify output directory, overrides setting in qdocconf file"));
85 outputDirOption.setValueName(QStringLiteral("dir"));
86 addOption(commandLineOption: outputDirOption);
87
88 outputFormatOption.setDescription(
89 QStringLiteral("Specify output format, overrides setting in qdocconf file"));
90 outputFormatOption.setValueName(QStringLiteral("format"));
91 addOption(commandLineOption: outputFormatOption);
92
93 noLinkErrorsOption.setDescription(
94 QStringLiteral("Do not print link errors (i.e. missing targets)"));
95 addOption(commandLineOption: noLinkErrorsOption);
96
97 autoLinkErrorsOption.setDescription(QStringLiteral("Show errors when automatic linking fails"));
98 addOption(commandLineOption: autoLinkErrorsOption);
99
100 debugOption.setDescription(QStringLiteral("Enable debug output"));
101 addOption(commandLineOption: debugOption);
102
103 atomsDumpOption.setDescription(QStringLiteral(
104 "Shows a human-readable form of the intermediate result of parsing a block-comment."));
105 addOption(commandLineOption: atomsDumpOption);
106
107 prepareOption.setDescription(
108 QStringLiteral("Run qdoc only to generate an index file, not the docs"));
109 addOption(commandLineOption: prepareOption);
110
111 generateOption.setDescription(
112 QStringLiteral("Run qdoc to read the index files and generate the docs"));
113 addOption(commandLineOption: generateOption);
114
115 logProgressOption.setDescription(QStringLiteral("Log progress on stderr."));
116 addOption(commandLineOption: logProgressOption);
117
118 singleExecOption.setDescription(QStringLiteral("Run qdoc once over all the qdoc conf files."));
119 addOption(commandLineOption: singleExecOption);
120
121 includePathOption.setFlags(QCommandLineOption::ShortOptionStyle);
122 addOption(commandLineOption: includePathOption);
123
124 addOption(commandLineOption: includePathSystemOption);
125
126 frameworkOption.setFlags(QCommandLineOption::ShortOptionStyle);
127 addOption(commandLineOption: frameworkOption);
128
129 timestampsOption.setDescription(QStringLiteral("Timestamp each qdoc log line."));
130 addOption(commandLineOption: timestampsOption);
131
132 useDocBookExtensions.setDescription(
133 QStringLiteral("Use the DocBook Library extensions for metadata."));
134 addOption(commandLineOption: useDocBookExtensions);
135}
136
137/*!
138 * \internal
139 *
140 * Create a list of arguments from the command line and/or file(s).
141 * This lets QDoc accept arguments contained in a file provided as a
142 * command-line argument prepended by '@'.
143 */
144static QStringList argumentsFromCommandLineAndFile(const QStringList &arguments)
145{
146 QStringList allArguments;
147 allArguments.reserve(asize: arguments.size());
148 for (const QString &argument : arguments) {
149 // "@file" doesn't start with a '-' so we can't use QCommandLineParser for it
150 if (argument.startsWith(c: QLatin1Char('@'))) {
151 QString optionsFile = argument;
152 optionsFile.remove(i: 0, len: 1);
153 if (optionsFile.isEmpty())
154 qFatal(msg: "The @ option requires an input file");
155 QFile f(optionsFile);
156 if (!f.open(flags: QIODevice::ReadOnly | QIODevice::Text))
157 qFatal(msg: "Cannot open options file specified with @: %ls",
158 qUtf16Printable(optionsFile));
159 while (!f.atEnd()) {
160 QString line = QString::fromLocal8Bit(ba: f.readLine().trimmed());
161 if (!line.isEmpty())
162 allArguments << line;
163 }
164 } else {
165 allArguments << argument;
166 }
167 }
168 return allArguments;
169}
170
171void QDocCommandLineParser::process(const QStringList &arguments)
172{
173 auto allArguments = argumentsFromCommandLineAndFile(arguments);
174 QCommandLineParser::process(arguments: allArguments);
175
176 if (isSet(option: singleExecOption) && isSet(option: indexDirOption))
177 qCWarning(lcQdoc) << "Warning: -indexdir option ignored: Index files are not used in single-exec mode.";
178}
179

source code of qttools/src/qdoc/qdoc/src/qdoc/qdoccommandlineparser.cpp