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 addOption(commandLineOption: defineOption);
52
53 dependsOption.setDescription(QStringLiteral("Specify dependent modules"));
54 dependsOption.setValueName(QStringLiteral("module"));
55 addOption(commandLineOption: dependsOption);
56
57 highlightingOption.setDescription(
58 QStringLiteral("Turn on syntax highlighting (makes qdoc run slower)"));
59 addOption(commandLineOption: highlightingOption);
60
61 showInternalOption.setDescription(QStringLiteral("Include content marked internal"));
62 addOption(commandLineOption: showInternalOption);
63
64 redirectDocumentationToDevNullOption.setDescription(
65 QStringLiteral("Save all documentation content to /dev/null. "
66 " Useful if someone is interested in qdoc errors only."));
67 addOption(commandLineOption: redirectDocumentationToDevNullOption);
68
69 noExamplesOption.setDescription(QStringLiteral("Do not generate documentation for examples"));
70 addOption(commandLineOption: noExamplesOption);
71
72 indexDirOption.setDescription(
73 QStringLiteral("Specify a directory where QDoc should search for index files to load"));
74 indexDirOption.setValueName(QStringLiteral("dir"));
75 addOption(commandLineOption: indexDirOption);
76
77 installDirOption.setDescription(QStringLiteral(
78 "Specify the directory where the output will be after running \"make install\""));
79 installDirOption.setValueName(QStringLiteral("dir"));
80 addOption(commandLineOption: installDirOption);
81
82 outputDirOption.setDescription(
83 QStringLiteral("Specify output directory, overrides setting in qdocconf file"));
84 outputDirOption.setValueName(QStringLiteral("dir"));
85 addOption(commandLineOption: outputDirOption);
86
87 outputFormatOption.setDescription(
88 QStringLiteral("Specify output format, overrides setting in qdocconf file"));
89 outputFormatOption.setValueName(QStringLiteral("format"));
90 addOption(commandLineOption: outputFormatOption);
91
92 noLinkErrorsOption.setDescription(
93 QStringLiteral("Do not print link errors (i.e. missing targets)"));
94 addOption(commandLineOption: noLinkErrorsOption);
95
96 autoLinkErrorsOption.setDescription(QStringLiteral("Show errors when automatic linking fails"));
97 addOption(commandLineOption: autoLinkErrorsOption);
98
99 debugOption.setDescription(QStringLiteral("Enable debug output"));
100 addOption(commandLineOption: debugOption);
101
102 atomsDumpOption.setDescription(QStringLiteral(
103 "Shows a human-readable form of the intermediate result of parsing a block-comment."));
104 addOption(commandLineOption: atomsDumpOption);
105
106 prepareOption.setDescription(
107 QStringLiteral("Run qdoc only to generate an index file, not the docs"));
108 addOption(commandLineOption: prepareOption);
109
110 generateOption.setDescription(
111 QStringLiteral("Run qdoc to read the index files and generate the docs"));
112 addOption(commandLineOption: generateOption);
113
114 logProgressOption.setDescription(QStringLiteral("Log progress on stderr."));
115 addOption(commandLineOption: logProgressOption);
116
117 singleExecOption.setDescription(QStringLiteral("Run qdoc once over all the qdoc conf files."));
118 addOption(commandLineOption: singleExecOption);
119
120 includePathOption.setFlags(QCommandLineOption::ShortOptionStyle);
121 addOption(commandLineOption: includePathOption);
122
123 addOption(commandLineOption: includePathSystemOption);
124
125 frameworkOption.setFlags(QCommandLineOption::ShortOptionStyle);
126 addOption(commandLineOption: frameworkOption);
127
128 timestampsOption.setDescription(QStringLiteral("Timestamp each qdoc log line."));
129 addOption(commandLineOption: timestampsOption);
130
131 useDocBookExtensions.setDescription(
132 QStringLiteral("Use the DocBook Library extensions for metadata."));
133 addOption(commandLineOption: useDocBookExtensions);
134}
135
136/*!
137 * \internal
138 *
139 * Create a list of arguments from the command line and/or file(s).
140 * This lets QDoc accept arguments contained in a file provided as a
141 * command-line argument prepended by '@'.
142 */
143static QStringList argumentsFromCommandLineAndFile(const QStringList &arguments)
144{
145 QStringList allArguments;
146 allArguments.reserve(asize: arguments.size());
147 for (const QString &argument : arguments) {
148 // "@file" doesn't start with a '-' so we can't use QCommandLineParser for it
149 if (argument.startsWith(c: QLatin1Char('@'))) {
150 QString optionsFile = argument;
151 optionsFile.remove(i: 0, len: 1);
152 if (optionsFile.isEmpty())
153 qFatal(msg: "The @ option requires an input file");
154 QFile f(optionsFile);
155 if (!f.open(flags: QIODevice::ReadOnly | QIODevice::Text))
156 qFatal(msg: "Cannot open options file specified with @: %ls",
157 qUtf16Printable(optionsFile));
158 while (!f.atEnd()) {
159 QString line = QString::fromLocal8Bit(ba: f.readLine().trimmed());
160 if (!line.isEmpty())
161 allArguments << line;
162 }
163 } else {
164 allArguments << argument;
165 }
166 }
167 return allArguments;
168}
169
170void QDocCommandLineParser::process(const QStringList &arguments)
171{
172 auto allArguments = argumentsFromCommandLineAndFile(arguments);
173 QCommandLineParser::process(arguments: allArguments);
174
175 if (isSet(option: singleExecOption) && isSet(option: indexDirOption))
176 qCWarning(lcQdoc) << "Warning: -indexdir option ignored: Index files are not used in single-exec mode.";
177}
178

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