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/TableGen/Error.h"
13 #include "llvm/ADT/STLExtras.h"
14 #include "llvm/ADT/SmallString.h"
15 #include "llvm/ADT/StringSwitch.h"
16 #include "llvm/ADT/Twine.h"
17 #include "llvm/TableGen/Record.h"
18 #include "llvm/TableGen/TableGenBackend.h"
19 #include <cctype>
20 #include <cstring>
21 #include <map>
22
23 using namespace llvm;
24
25 namespace {
26 struct DocumentedOption {
27 Record *Option;
28 std::vector<Record*> Aliases;
29 };
30 struct DocumentedGroup;
31 struct Documentation {
32 std::vector<DocumentedGroup> Groups;
33 std::vector<DocumentedOption> Options;
34 };
35 struct DocumentedGroup : Documentation {
36 Record *Group;
37 };
38
39 // Reorganize the records into a suitable form for emitting documentation.
extractDocumentation(RecordKeeper & Records)40 Documentation extractDocumentation(RecordKeeper &Records) {
41 Documentation Result;
42
43 // Build the tree of groups. The root in the tree is the fake option group
44 // (Record*)nullptr, which contains all top-level groups and options.
45 std::map<Record*, std::vector<Record*> > OptionsInGroup;
46 std::map<Record*, std::vector<Record*> > GroupsInGroup;
47 std::map<Record*, std::vector<Record*> > Aliases;
48
49 std::map<std::string, Record*> OptionsByName;
50 for (Record *R : Records.getAllDerivedDefinitions("Option"))
51 OptionsByName[std::string(R->getValueAsString("Name"))] = R;
52
53 auto Flatten = [](Record *R) {
54 return R->getValue("DocFlatten") && R->getValueAsBit("DocFlatten");
55 };
56
57 auto SkipFlattened = [&](Record *R) -> Record* {
58 while (R && Flatten(R)) {
59 auto *G = dyn_cast<DefInit>(R->getValueInit("Group"));
60 if (!G)
61 return nullptr;
62 R = G->getDef();
63 }
64 return R;
65 };
66
67 for (Record *R : Records.getAllDerivedDefinitions("OptionGroup")) {
68 if (Flatten(R))
69 continue;
70
71 Record *Group = nullptr;
72 if (auto *G = dyn_cast<DefInit>(R->getValueInit("Group")))
73 Group = SkipFlattened(G->getDef());
74 GroupsInGroup[Group].push_back(R);
75 }
76
77 for (Record *R : Records.getAllDerivedDefinitions("Option")) {
78 if (auto *A = dyn_cast<DefInit>(R->getValueInit("Alias"))) {
79 Aliases[A->getDef()].push_back(R);
80 continue;
81 }
82
83 // Pretend no-X and Xno-Y options are aliases of X and XY.
84 std::string Name = std::string(R->getValueAsString("Name"));
85 if (Name.size() >= 4) {
86 if (Name.substr(0, 3) == "no-" && OptionsByName[Name.substr(3)]) {
87 Aliases[OptionsByName[Name.substr(3)]].push_back(R);
88 continue;
89 }
90 if (Name.substr(1, 3) == "no-" && OptionsByName[Name[0] + Name.substr(4)]) {
91 Aliases[OptionsByName[Name[0] + Name.substr(4)]].push_back(R);
92 continue;
93 }
94 }
95
96 Record *Group = nullptr;
97 if (auto *G = dyn_cast<DefInit>(R->getValueInit("Group")))
98 Group = SkipFlattened(G->getDef());
99 OptionsInGroup[Group].push_back(R);
100 }
101
102 auto CompareByName = [](Record *A, Record *B) {
103 return A->getValueAsString("Name") < B->getValueAsString("Name");
104 };
105
106 auto CompareByLocation = [](Record *A, Record *B) {
107 return A->getLoc()[0].getPointer() < B->getLoc()[0].getPointer();
108 };
109
110 auto DocumentationForOption = [&](Record *R) -> DocumentedOption {
111 auto &A = Aliases[R];
112 llvm::sort(A, CompareByName);
113 return {R, std::move(A)};
114 };
115
116 std::function<Documentation(Record *)> DocumentationForGroup =
117 [&](Record *R) -> Documentation {
118 Documentation D;
119
120 auto &Groups = GroupsInGroup[R];
121 llvm::sort(Groups, CompareByLocation);
122 for (Record *G : Groups) {
123 D.Groups.emplace_back();
124 D.Groups.back().Group = G;
125 Documentation &Base = D.Groups.back();
126 Base = DocumentationForGroup(G);
127 }
128
129 auto &Options = OptionsInGroup[R];
130 llvm::sort(Options, CompareByName);
131 for (Record *O : Options)
132 D.Options.push_back(DocumentationForOption(O));
133
134 return D;
135 };
136
137 return DocumentationForGroup(nullptr);
138 }
139
140 // Get the first and successive separators to use for an OptionKind.
getSeparatorsForKind(const Record * OptionKind)141 std::pair<StringRef,StringRef> getSeparatorsForKind(const Record *OptionKind) {
142 return StringSwitch<std::pair<StringRef, StringRef>>(OptionKind->getName())
143 .Cases("KIND_JOINED", "KIND_JOINED_OR_SEPARATE",
144 "KIND_JOINED_AND_SEPARATE",
145 "KIND_REMAINING_ARGS_JOINED", {"", " "})
146 .Case("KIND_COMMAJOINED", {"", ","})
147 .Default({" ", " "});
148 }
149
150 const unsigned UnlimitedArgs = unsigned(-1);
151
152 // Get the number of arguments expected for an option, or -1 if any number of
153 // arguments are accepted.
getNumArgsForKind(Record * OptionKind,const Record * Option)154 unsigned getNumArgsForKind(Record *OptionKind, const Record *Option) {
155 return StringSwitch<unsigned>(OptionKind->getName())
156 .Cases("KIND_JOINED", "KIND_JOINED_OR_SEPARATE", "KIND_SEPARATE", 1)
157 .Cases("KIND_REMAINING_ARGS", "KIND_REMAINING_ARGS_JOINED",
158 "KIND_COMMAJOINED", UnlimitedArgs)
159 .Case("KIND_JOINED_AND_SEPARATE", 2)
160 .Case("KIND_MULTIARG", Option->getValueAsInt("NumArgs"))
161 .Default(0);
162 }
163
hasFlag(const Record * OptionOrGroup,StringRef OptionFlag)164 bool hasFlag(const Record *OptionOrGroup, StringRef OptionFlag) {
165 for (const Record *Flag : OptionOrGroup->getValueAsListOfDefs("Flags"))
166 if (Flag->getName() == OptionFlag)
167 return true;
168 return false;
169 }
170
isExcluded(const Record * OptionOrGroup,const Record * DocInfo)171 bool isExcluded(const Record *OptionOrGroup, const Record *DocInfo) {
172 // FIXME: Provide a flag to specify the set of exclusions.
173 for (StringRef Exclusion : DocInfo->getValueAsListOfStrings("ExcludedFlags"))
174 if (hasFlag(OptionOrGroup, Exclusion))
175 return true;
176 return false;
177 }
178
escapeRST(StringRef Str)179 std::string escapeRST(StringRef Str) {
180 std::string Out;
181 for (auto K : Str) {
182 if (StringRef("`*|_[]\\").count(K))
183 Out.push_back('\\');
184 Out.push_back(K);
185 }
186 return Out;
187 }
188
getSphinxOptionID(StringRef OptionName)189 StringRef getSphinxOptionID(StringRef OptionName) {
190 for (auto I = OptionName.begin(), E = OptionName.end(); I != E; ++I)
191 if (!isalnum(*I) && *I != '-')
192 return OptionName.substr(0, I - OptionName.begin());
193 return OptionName;
194 }
195
canSphinxCopeWithOption(const Record * Option)196 bool canSphinxCopeWithOption(const Record *Option) {
197 // HACK: Work arond sphinx's inability to cope with punctuation-only options
198 // such as /? by suppressing them from the option list.
199 for (char C : Option->getValueAsString("Name"))
200 if (isalnum(C))
201 return true;
202 return false;
203 }
204
emitHeading(int Depth,std::string Heading,raw_ostream & OS)205 void emitHeading(int Depth, std::string Heading, raw_ostream &OS) {
206 assert(Depth < 8 && "groups nested too deeply");
207 OS << Heading << '\n'
208 << std::string(Heading.size(), "=~-_'+<>"[Depth]) << "\n";
209 }
210
211 /// Get the value of field \p Primary, if possible. If \p Primary does not
212 /// exist, get the value of \p Fallback and escape it for rST emission.
getRSTStringWithTextFallback(const Record * R,StringRef Primary,StringRef Fallback)213 std::string getRSTStringWithTextFallback(const Record *R, StringRef Primary,
214 StringRef Fallback) {
215 for (auto Field : {Primary, Fallback}) {
216 if (auto *V = R->getValue(Field)) {
217 StringRef Value;
218 if (auto *SV = dyn_cast_or_null<StringInit>(V->getValue()))
219 Value = SV->getValue();
220 if (!Value.empty())
221 return Field == Primary ? Value.str() : escapeRST(Value);
222 }
223 }
224 return std::string(StringRef());
225 }
226
emitOptionWithArgs(StringRef Prefix,const Record * Option,ArrayRef<StringRef> Args,raw_ostream & OS)227 void emitOptionWithArgs(StringRef Prefix, const Record *Option,
228 ArrayRef<StringRef> Args, raw_ostream &OS) {
229 OS << Prefix << escapeRST(Option->getValueAsString("Name"));
230
231 std::pair<StringRef, StringRef> Separators =
232 getSeparatorsForKind(Option->getValueAsDef("Kind"));
233
234 StringRef Separator = Separators.first;
235 for (auto Arg : Args) {
236 OS << Separator << escapeRST(Arg);
237 Separator = Separators.second;
238 }
239 }
240
emitOptionName(StringRef Prefix,const Record * Option,raw_ostream & OS)241 void emitOptionName(StringRef Prefix, const Record *Option, raw_ostream &OS) {
242 // Find the arguments to list after the option.
243 unsigned NumArgs = getNumArgsForKind(Option->getValueAsDef("Kind"), Option);
244 bool HasMetaVarName = !Option->isValueUnset("MetaVarName");
245
246 std::vector<std::string> Args;
247 if (HasMetaVarName)
248 Args.push_back(std::string(Option->getValueAsString("MetaVarName")));
249 else if (NumArgs == 1)
250 Args.push_back("<arg>");
251
252 // Fill up arguments if this option didn't provide a meta var name or it
253 // supports an unlimited number of arguments. We can't see how many arguments
254 // already are in a meta var name, so assume it has right number. This is
255 // needed for JoinedAndSeparate options so that there arent't too many
256 // arguments.
257 if (!HasMetaVarName || NumArgs == UnlimitedArgs) {
258 while (Args.size() < NumArgs) {
259 Args.push_back(("<arg" + Twine(Args.size() + 1) + ">").str());
260 // Use '--args <arg1> <arg2>...' if any number of args are allowed.
261 if (Args.size() == 2 && NumArgs == UnlimitedArgs) {
262 Args.back() += "...";
263 break;
264 }
265 }
266 }
267
268 emitOptionWithArgs(Prefix, Option, std::vector<StringRef>(Args.begin(), Args.end()), OS);
269
270 auto AliasArgs = Option->getValueAsListOfStrings("AliasArgs");
271 if (!AliasArgs.empty()) {
272 Record *Alias = Option->getValueAsDef("Alias");
273 OS << " (equivalent to ";
274 emitOptionWithArgs(
275 Alias->getValueAsListOfStrings("Prefixes").front(), Alias,
276 AliasArgs, OS);
277 OS << ")";
278 }
279 }
280
emitOptionNames(const Record * Option,raw_ostream & OS,bool EmittedAny)281 bool emitOptionNames(const Record *Option, raw_ostream &OS, bool EmittedAny) {
282 for (auto &Prefix : Option->getValueAsListOfStrings("Prefixes")) {
283 if (EmittedAny)
284 OS << ", ";
285 emitOptionName(Prefix, Option, OS);
286 EmittedAny = true;
287 }
288 return EmittedAny;
289 }
290
291 template <typename Fn>
forEachOptionName(const DocumentedOption & Option,const Record * DocInfo,Fn F)292 void forEachOptionName(const DocumentedOption &Option, const Record *DocInfo,
293 Fn F) {
294 F(Option.Option);
295
296 for (auto *Alias : Option.Aliases)
297 if (!isExcluded(Alias, DocInfo) && canSphinxCopeWithOption(Option.Option))
298 F(Alias);
299 }
300
emitOption(const DocumentedOption & Option,const Record * DocInfo,raw_ostream & OS)301 void emitOption(const DocumentedOption &Option, const Record *DocInfo,
302 raw_ostream &OS) {
303 if (isExcluded(Option.Option, DocInfo))
304 return;
305 if (Option.Option->getValueAsDef("Kind")->getName() == "KIND_UNKNOWN" ||
306 Option.Option->getValueAsDef("Kind")->getName() == "KIND_INPUT")
307 return;
308 if (!canSphinxCopeWithOption(Option.Option))
309 return;
310
311 // HACK: Emit a different program name with each option to work around
312 // sphinx's inability to cope with options that differ only by punctuation
313 // (eg -ObjC vs -ObjC++, -G vs -G=).
314 std::vector<std::string> SphinxOptionIDs;
315 forEachOptionName(Option, DocInfo, [&](const Record *Option) {
316 for (auto &Prefix : Option->getValueAsListOfStrings("Prefixes"))
317 SphinxOptionIDs.push_back(std::string(getSphinxOptionID(
318 (Prefix + Option->getValueAsString("Name")).str())));
319 });
320 assert(!SphinxOptionIDs.empty() && "no flags for option");
321 static std::map<std::string, int> NextSuffix;
322 int SphinxWorkaroundSuffix = NextSuffix[*std::max_element(
323 SphinxOptionIDs.begin(), SphinxOptionIDs.end(),
324 [&](const std::string &A, const std::string &B) {
325 return NextSuffix[A] < NextSuffix[B];
326 })];
327 for (auto &S : SphinxOptionIDs)
328 NextSuffix[S] = SphinxWorkaroundSuffix + 1;
329 if (SphinxWorkaroundSuffix)
330 OS << ".. program:: " << DocInfo->getValueAsString("Program")
331 << SphinxWorkaroundSuffix << "\n";
332
333 // Emit the names of the option.
334 OS << ".. option:: ";
335 bool EmittedAny = false;
336 forEachOptionName(Option, DocInfo, [&](const Record *Option) {
337 EmittedAny = emitOptionNames(Option, OS, EmittedAny);
338 });
339 if (SphinxWorkaroundSuffix)
340 OS << "\n.. program:: " << DocInfo->getValueAsString("Program");
341 OS << "\n\n";
342
343 // Emit the description, if we have one.
344 std::string Description =
345 getRSTStringWithTextFallback(Option.Option, "DocBrief", "HelpText");
346 if (!Description.empty())
347 OS << Description << "\n\n";
348 }
349
350 void emitDocumentation(int Depth, const Documentation &Doc,
351 const Record *DocInfo, raw_ostream &OS);
352
emitGroup(int Depth,const DocumentedGroup & Group,const Record * DocInfo,raw_ostream & OS)353 void emitGroup(int Depth, const DocumentedGroup &Group, const Record *DocInfo,
354 raw_ostream &OS) {
355 if (isExcluded(Group.Group, DocInfo))
356 return;
357
358 emitHeading(Depth,
359 getRSTStringWithTextFallback(Group.Group, "DocName", "Name"), OS);
360
361 // Emit the description, if we have one.
362 std::string Description =
363 getRSTStringWithTextFallback(Group.Group, "DocBrief", "HelpText");
364 if (!Description.empty())
365 OS << Description << "\n\n";
366
367 // Emit contained options and groups.
368 emitDocumentation(Depth + 1, Group, DocInfo, OS);
369 }
370
emitDocumentation(int Depth,const Documentation & Doc,const Record * DocInfo,raw_ostream & OS)371 void emitDocumentation(int Depth, const Documentation &Doc,
372 const Record *DocInfo, raw_ostream &OS) {
373 for (auto &O : Doc.Options)
374 emitOption(O, DocInfo, OS);
375 for (auto &G : Doc.Groups)
376 emitGroup(Depth, G, DocInfo, OS);
377 }
378
379 } // namespace
380
EmitClangOptDocs(RecordKeeper & Records,raw_ostream & OS)381 void clang::EmitClangOptDocs(RecordKeeper &Records, raw_ostream &OS) {
382 const Record *DocInfo = Records.getDef("GlobalDocumentation");
383 if (!DocInfo) {
384 PrintFatalError("The GlobalDocumentation top-level definition is missing, "
385 "no documentation will be generated.");
386 return;
387 }
388 OS << DocInfo->getValueAsString("Intro") << "\n";
389 OS << ".. program:: " << DocInfo->getValueAsString("Program") << "\n";
390
391 emitDocumentation(0, extractDocumentation(Records), DocInfo, OS);
392 }
393