1//===-- ClangOptionDocEmitter.cpp - Documentation for command line flags --===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7// FIXME: Once this has stabilized, consider moving it to LLVM.
8//
9//===----------------------------------------------------------------------===//
10
11#include "TableGenBackends.h"
12#include "llvm/ADT/STLExtras.h"
13#include "llvm/ADT/StringSwitch.h"
14#include "llvm/ADT/Twine.h"
15#include "llvm/TableGen/Error.h"
16#include "llvm/TableGen/Record.h"
17#include "llvm/TableGen/TableGenBackend.h"
18#include <cctype>
19#include <cstring>
20#include <map>
21
22using namespace llvm;
23
24namespace {
25struct DocumentedOption {
26 const Record *Option;
27 std::vector<const Record *> Aliases;
28};
29struct DocumentedGroup;
30struct Documentation {
31 std::vector<DocumentedGroup> Groups;
32 std::vector<DocumentedOption> Options;
33
34 bool empty() {
35 return Groups.empty() && Options.empty();
36 }
37};
38struct DocumentedGroup : Documentation {
39 const Record *Group;
40};
41
42static bool hasFlag(const Record *Option, StringRef OptionFlag,
43 StringRef FlagsField) {
44 for (const Record *Flag : Option->getValueAsListOfDefs(FieldName: FlagsField))
45 if (Flag->getName() == OptionFlag)
46 return true;
47 if (const DefInit *DI = dyn_cast<DefInit>(Val: Option->getValueInit(FieldName: "Group")))
48 for (const Record *Flag : DI->getDef()->getValueAsListOfDefs(FieldName: FlagsField))
49 if (Flag->getName() == OptionFlag)
50 return true;
51 return false;
52}
53
54static bool isOptionVisible(const Record *Option, const Record *DocInfo) {
55 for (StringRef IgnoredFlag : DocInfo->getValueAsListOfStrings(FieldName: "IgnoreFlags"))
56 if (hasFlag(Option, OptionFlag: IgnoredFlag, FlagsField: "Flags"))
57 return false;
58 for (StringRef Mask : DocInfo->getValueAsListOfStrings(FieldName: "VisibilityMask"))
59 if (hasFlag(Option, OptionFlag: Mask, FlagsField: "Visibility"))
60 return true;
61 return false;
62}
63
64// Reorganize the records into a suitable form for emitting documentation.
65Documentation extractDocumentation(const RecordKeeper &Records,
66 const Record *DocInfo) {
67 // Build the tree of groups. The root in the tree is the fake option group
68 // (Record*)nullptr, which contains all top-level groups and options.
69 std::map<const Record *, std::vector<const Record *>> OptionsInGroup;
70 std::map<const Record *, std::vector<const Record *>> GroupsInGroup;
71 std::map<const Record *, std::vector<const Record *>> Aliases;
72
73 std::map<std::string, const Record *> OptionsByName;
74 for (const Record *R : Records.getAllDerivedDefinitions(ClassName: "Option"))
75 OptionsByName[std::string(R->getValueAsString(FieldName: "Name"))] = R;
76
77 auto Flatten = [](const Record *R) {
78 return R->getValue(Name: "DocFlatten") && R->getValueAsBit(FieldName: "DocFlatten");
79 };
80
81 auto SkipFlattened = [&](const Record *R) -> const Record * {
82 while (R && Flatten(R)) {
83 auto *G = dyn_cast<DefInit>(Val: R->getValueInit(FieldName: "Group"));
84 if (!G)
85 return nullptr;
86 R = G->getDef();
87 }
88 return R;
89 };
90
91 for (const Record *R : Records.getAllDerivedDefinitions(ClassName: "OptionGroup")) {
92 if (Flatten(R))
93 continue;
94
95 const Record *Group = nullptr;
96 if (auto *G = dyn_cast<DefInit>(Val: R->getValueInit(FieldName: "Group")))
97 Group = SkipFlattened(G->getDef());
98 GroupsInGroup[Group].push_back(x: R);
99 }
100
101 for (const Record *R : Records.getAllDerivedDefinitions(ClassName: "Option")) {
102 if (auto *A = dyn_cast<DefInit>(Val: R->getValueInit(FieldName: "Alias"))) {
103 Aliases[A->getDef()].push_back(x: R);
104 continue;
105 }
106
107 // Pretend no-X and Xno-Y options are aliases of X and XY.
108 std::string Name = std::string(R->getValueAsString(FieldName: "Name"));
109 if (Name.size() >= 4) {
110 if (Name.substr(pos: 0, n: 3) == "no-") {
111 if (const Record *Opt = OptionsByName[Name.substr(pos: 3)]) {
112 Aliases[Opt].push_back(x: R);
113 continue;
114 }
115 }
116 if (Name.substr(pos: 1, n: 3) == "no-") {
117 if (const Record *Opt = OptionsByName[Name[0] + Name.substr(pos: 4)]) {
118 Aliases[Opt].push_back(x: R);
119 continue;
120 }
121 }
122 }
123
124 const Record *Group = nullptr;
125 if (auto *G = dyn_cast<DefInit>(Val: R->getValueInit(FieldName: "Group")))
126 Group = SkipFlattened(G->getDef());
127 OptionsInGroup[Group].push_back(x: R);
128 }
129
130 auto CompareByName = [](const Record *A, const Record *B) {
131 return A->getValueAsString(FieldName: "Name") < B->getValueAsString(FieldName: "Name");
132 };
133
134 auto CompareByLocation = [](const Record *A, const Record *B) {
135 return A->getLoc()[0].getPointer() < B->getLoc()[0].getPointer();
136 };
137
138 auto DocumentationForOption = [&](const Record *R) -> DocumentedOption {
139 auto &A = Aliases[R];
140 sort(C&: A, Comp: CompareByName);
141 return {.Option: R, .Aliases: std::move(A)};
142 };
143
144 std::function<Documentation(const Record *)> DocumentationForGroup =
145 [&](const Record *R) -> Documentation {
146 Documentation D;
147
148 auto &Groups = GroupsInGroup[R];
149 sort(C&: Groups, Comp: CompareByLocation);
150 for (const Record *G : Groups) {
151 D.Groups.emplace_back();
152 D.Groups.back().Group = G;
153 Documentation &Base = D.Groups.back();
154 Base = DocumentationForGroup(G);
155 if (Base.empty())
156 D.Groups.pop_back();
157 }
158
159 auto &Options = OptionsInGroup[R];
160 sort(C&: Options, Comp: CompareByName);
161 for (const Record *O : Options)
162 if (isOptionVisible(Option: O, DocInfo))
163 D.Options.push_back(x: DocumentationForOption(O));
164
165 return D;
166 };
167
168 return DocumentationForGroup(nullptr);
169}
170
171// Get the first and successive separators to use for an OptionKind.
172std::pair<StringRef,StringRef> getSeparatorsForKind(const Record *OptionKind) {
173 return StringSwitch<std::pair<StringRef, StringRef>>(OptionKind->getName())
174 .Cases(CaseStrings: {"KIND_JOINED", "KIND_JOINED_OR_SEPARATE",
175 "KIND_JOINED_AND_SEPARATE", "KIND_REMAINING_ARGS_JOINED"},
176 Value: {"", " "})
177 .Case(S: "KIND_COMMAJOINED", Value: {"", ","})
178 .Default(Value: {" ", " "});
179}
180
181const unsigned UnlimitedArgs = unsigned(-1);
182
183// Get the number of arguments expected for an option, or -1 if any number of
184// arguments are accepted.
185unsigned getNumArgsForKind(const Record *OptionKind, const Record *Option) {
186 return StringSwitch<unsigned>(OptionKind->getName())
187 .Cases(CaseStrings: {"KIND_JOINED", "KIND_JOINED_OR_SEPARATE", "KIND_SEPARATE",
188 "KIND_SEPARATE_OR_EQ"},
189 Value: 1)
190 .Cases(CaseStrings: {"KIND_REMAINING_ARGS", "KIND_REMAINING_ARGS_JOINED",
191 "KIND_COMMAJOINED"},
192 Value: UnlimitedArgs)
193 .Case(S: "KIND_JOINED_AND_SEPARATE", Value: 2)
194 .Case(S: "KIND_MULTIARG", Value: Option->getValueAsInt(FieldName: "NumArgs"))
195 .Default(Value: 0);
196}
197
198std::string escapePlainTextForMarkdown(StringRef Str) {
199 std::string Out;
200 for (char C : Str) {
201 if (StringRef("*[]\\<>").count(C))
202 Out.push_back(c: '\\');
203 Out.push_back(c: C);
204 }
205 return Out;
206}
207
208StringRef getSphinxOptionID(StringRef OptionName) {
209 return OptionName.take_while(F: [](char C) { return isalnum(C) || C == '-'; });
210}
211
212bool canSphinxCopeWithOption(const Record *Option) {
213 // HACK: Work arond sphinx's inability to cope with punctuation-only options
214 // such as /? by suppressing them from the option list.
215 for (char C : Option->getValueAsString(FieldName: "Name"))
216 if (isalnum(C))
217 return true;
218 return false;
219}
220
221void emitHeading(int Depth, const std::string &Heading, raw_ostream &OS) {
222 assert(Depth < 5 && "groups nested too deeply");
223 OS << std::string(Depth + 2, '#') << ' ' << Heading << "\n\n";
224}
225
226/// Get the value of field \p Primary, if possible. If \p Primary does not
227/// exist, get the value of \p Fallback and escape it for Markdown emission.
228std::string getMarkdownStringWithTextFallback(const Record *R,
229 StringRef Primary,
230 StringRef Fallback) {
231 for (auto Field : {Primary, Fallback}) {
232 if (auto *V = R->getValue(Name: Field)) {
233 StringRef Value;
234 if (auto *SV = dyn_cast_or_null<StringInit>(Val: V->getValue()))
235 Value = SV->getValue();
236 if (!Value.empty())
237 return Field == Primary ? Value.str()
238 : escapePlainTextForMarkdown(Str: Value);
239 }
240 }
241 return std::string(StringRef());
242}
243
244// The Sphinx option directive contents do not need to be escaped. They use
245// standard usage conventions, where angle brackets are values, and square
246// brackets are optional arguments. See
247// https://www.sphinx-doc.org/en/master/usage/domains/standard.html#directive-option
248void emitOptionWithArgs(StringRef Prefix, const Record *Option,
249 ArrayRef<StringRef> Args, raw_ostream &OS) {
250 OS << Prefix << Option->getValueAsString(FieldName: "Name");
251
252 std::pair<StringRef, StringRef> Separators =
253 getSeparatorsForKind(OptionKind: Option->getValueAsDef(FieldName: "Kind"));
254
255 StringRef Separator = Separators.first;
256 for (auto Arg : Args) {
257 OS << Separator << Arg;
258 Separator = Separators.second;
259 }
260}
261
262constexpr StringLiteral DefaultMetaVarName = "<arg>";
263
264void emitOptionName(StringRef Prefix, const Record *Option, raw_ostream &OS) {
265 // Find the arguments to list after the option.
266 unsigned NumArgs = getNumArgsForKind(OptionKind: Option->getValueAsDef(FieldName: "Kind"), Option);
267 bool HasMetaVarName = !Option->isValueUnset(FieldName: "MetaVarName");
268
269 std::vector<std::string> Args;
270 if (HasMetaVarName)
271 Args.push_back(x: std::string(Option->getValueAsString(FieldName: "MetaVarName")));
272 else if (NumArgs == 1)
273 Args.push_back(x: DefaultMetaVarName.str());
274
275 // Fill up arguments if this option didn't provide a meta var name or it
276 // supports an unlimited number of arguments. We can't see how many arguments
277 // already are in a meta var name, so assume it has right number. This is
278 // needed for JoinedAndSeparate options so that there arent't too many
279 // arguments.
280 if (!HasMetaVarName || NumArgs == UnlimitedArgs) {
281 while (Args.size() < NumArgs) {
282 Args.push_back(x: ("<arg" + Twine(Args.size() + 1) + ">").str());
283 // Use '--args <arg1> <arg2>...' if any number of args are allowed.
284 if (Args.size() == 2 && NumArgs == UnlimitedArgs) {
285 Args.back() += "...";
286 break;
287 }
288 }
289 }
290
291 emitOptionWithArgs(Prefix, Option,
292 Args: std::vector<StringRef>(Args.begin(), Args.end()), OS);
293 if (Option->getValueAsDef(FieldName: "Kind")->getName() == "KIND_SEPARATE_OR_EQ")
294 OS << ", " << Prefix << Option->getValueAsString(FieldName: "Name") << '=' << Args[0];
295
296 auto AliasArgs = Option->getValueAsListOfStrings(FieldName: "AliasArgs");
297 if (!AliasArgs.empty()) {
298 const Record *Alias = Option->getValueAsDef(FieldName: "Alias");
299 OS << " (equivalent to ";
300 emitOptionWithArgs(
301 Prefix: Alias->getValueAsListOfStrings(FieldName: "Prefixes").front(), Option: Alias,
302 Args: AliasArgs, OS);
303 OS << ")";
304 }
305}
306
307bool emitOptionNames(const Record *Option, raw_ostream &OS, bool EmittedAny) {
308 for (auto &Prefix : Option->getValueAsListOfStrings(FieldName: "Prefixes")) {
309 if (EmittedAny)
310 OS << ", ";
311 emitOptionName(Prefix, Option, OS);
312 EmittedAny = true;
313 }
314 return EmittedAny;
315}
316
317template <typename Fn>
318void forEachOptionName(const DocumentedOption &Option, const Record *DocInfo,
319 Fn F) {
320 F(Option.Option);
321
322 for (auto *Alias : Option.Aliases)
323 if (isOptionVisible(Option: Alias, DocInfo) &&
324 canSphinxCopeWithOption(Option: Option.Option))
325 F(Alias);
326}
327
328void emitOption(const DocumentedOption &Option, const Record *DocInfo,
329 raw_ostream &OS) {
330 if (Option.Option->getValueAsDef(FieldName: "Kind")->getName() == "KIND_UNKNOWN" ||
331 Option.Option->getValueAsDef(FieldName: "Kind")->getName() == "KIND_INPUT")
332 return;
333 if (!canSphinxCopeWithOption(Option: Option.Option))
334 return;
335
336 // HACK: Emit a different program name with each option to work around
337 // sphinx's inability to cope with options that differ only by punctuation
338 // (eg -ObjC vs -ObjC++, -G vs -G=).
339 std::vector<std::string> SphinxOptionIDs;
340 forEachOptionName(Option, DocInfo, F: [&](const Record *Option) {
341 for (auto &Prefix : Option->getValueAsListOfStrings(FieldName: "Prefixes"))
342 SphinxOptionIDs.push_back(x: std::string(getSphinxOptionID(
343 OptionName: (Prefix + Option->getValueAsString(FieldName: "Name")).str())));
344 });
345 assert(!SphinxOptionIDs.empty() && "no flags for option");
346 static std::map<std::string, int> NextSuffix;
347 int SphinxWorkaroundSuffix = NextSuffix[*llvm::max_element(
348 Range&: SphinxOptionIDs, C: [&](const std::string &A, const std::string &B) {
349 return NextSuffix[A] < NextSuffix[B];
350 })];
351 for (auto &S : SphinxOptionIDs)
352 NextSuffix[S] = SphinxWorkaroundSuffix + 1;
353
354 std::string Program = DocInfo->getValueAsString(FieldName: "Program").lower();
355 if (SphinxWorkaroundSuffix)
356 OS << ":::{program} " << Program << SphinxWorkaroundSuffix << "\n:::\n\n";
357
358 // Emit the names of the option.
359 OS << ":::{option} ";
360 bool EmittedAny = false;
361 forEachOptionName(Option, DocInfo, F: [&](const Record *Option) {
362 EmittedAny = emitOptionNames(Option, OS, EmittedAny);
363 });
364 OS << "\n:::\n\n";
365
366 // Emit the description, if we have one.
367 const Record *R = Option.Option;
368 std::string Description;
369
370 // Prefer a program specific help string.
371 // This is a list of (visibilities, string) pairs.
372 for (const Record *VisibilityHelp :
373 R->getValueAsListOfDefs(FieldName: "HelpTextsForVariants")) {
374 // This is a list of visibilities.
375 ArrayRef<const Init *> Visibilities =
376 VisibilityHelp->getValueAsListInit(FieldName: "Visibilities")->getElements();
377
378 // See if any of the program's visibilities are in the list.
379 for (StringRef DocInfoMask :
380 DocInfo->getValueAsListOfStrings(FieldName: "VisibilityMask")) {
381 for (const Init *Visibility : Visibilities) {
382 if (Visibility->getAsUnquotedString() == DocInfoMask) {
383 // Use the first one we find.
384 Description = escapePlainTextForMarkdown(
385 Str: VisibilityHelp->getValueAsString(FieldName: "Text"));
386 break;
387 }
388 }
389 if (!Description.empty())
390 break;
391 }
392
393 if (!Description.empty())
394 break;
395 }
396
397 // If there's not a program specific string, use the default one.
398 if (Description.empty())
399 Description = getMarkdownStringWithTextFallback(R, Primary: "DocBrief", Fallback: "HelpText");
400
401 if (!isa<UnsetInit>(Val: R->getValueInit(FieldName: "Values"))) {
402 if (!Description.empty() && Description.back() != '.')
403 Description.push_back(c: '.');
404
405 StringRef MetaVarName;
406 if (!isa<UnsetInit>(Val: R->getValueInit(FieldName: "MetaVarName")))
407 MetaVarName = R->getValueAsString(FieldName: "MetaVarName");
408 else
409 MetaVarName = DefaultMetaVarName;
410
411 SmallVector<StringRef> Values;
412 SplitString(Source: R->getValueAsString(FieldName: "Values"), OutFragments&: Values, Delimiters: ",");
413 Description += " " + escapePlainTextForMarkdown(Str: MetaVarName) + " must be '";
414 if (Values.size() > 1) {
415 for (auto [I, Value] : enumerate(First: drop_end(RangeOrContainer&: Values))) {
416 if (I)
417 Description += "', '";
418 Description += escapePlainTextForMarkdown(Str: Value);
419 }
420 Description += "' or '";
421 }
422 Description += escapePlainTextForMarkdown(Str: Values.back()) + "'.";
423 }
424
425 if (!Description.empty())
426 OS << Description << "\n\n";
427
428 if (SphinxWorkaroundSuffix)
429 OS << ":::{program} " << Program << "\n:::\n\n";
430}
431
432void emitDocumentation(int Depth, const Documentation &Doc,
433 const Record *DocInfo, raw_ostream &OS);
434
435void emitGroup(int Depth, const DocumentedGroup &Group, const Record *DocInfo,
436 raw_ostream &OS) {
437 emitHeading(Depth,
438 Heading: getMarkdownStringWithTextFallback(R: Group.Group, Primary: "DocName", Fallback: "Name"),
439 OS);
440
441 // Emit the description, if we have one.
442 std::string Description =
443 getMarkdownStringWithTextFallback(R: Group.Group, Primary: "DocBrief", Fallback: "HelpText");
444 if (!Description.empty())
445 OS << Description << "\n\n";
446
447 // Emit contained options and groups.
448 emitDocumentation(Depth: Depth + 1, Doc: Group, DocInfo, OS);
449}
450
451void emitDocumentation(int Depth, const Documentation &Doc,
452 const Record *DocInfo, raw_ostream &OS) {
453 for (auto &O : Doc.Options)
454 emitOption(Option: O, DocInfo, OS);
455 for (auto &G : Doc.Groups)
456 emitGroup(Depth, Group: G, DocInfo, OS);
457}
458
459} // namespace
460
461void clang::EmitClangOptDocs(const RecordKeeper &Records, raw_ostream &OS) {
462 const Record *DocInfo = Records.getDef(Name: "GlobalDocumentation");
463 if (!DocInfo) {
464 PrintFatalError(Msg: "The GlobalDocumentation top-level definition is missing, "
465 "no documentation will be generated.");
466 return;
467 }
468 OS << DocInfo->getValueAsString(FieldName: "Intro") << "\n";
469 OS << ":::{program} " << DocInfo->getValueAsString(FieldName: "Program").lower()
470 << "\n:::\n\n";
471
472 emitDocumentation(Depth: 0, Doc: extractDocumentation(Records, DocInfo), DocInfo, OS);
473}
474