1 //===-- ClangDocMain.cpp - ClangDoc -----------------------------*- C++ -*-===//
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 //===----------------------------------------------------------------------===//
8 //
9 // This tool for generating C and C++ documentation from source code
10 // and comments. Generally, it runs a LibTooling FrontendAction on source files,
11 // mapping each declaration in those files to its USR and serializing relevant
12 // information into LLVM bitcode. It then runs a pass over the collected
13 // declaration information, reducing by USR. There is an option to dump this
14 // intermediate result to bitcode. Finally, it hands the reduced information
15 // off to a generator, which does the final parsing from the intermediate
16 // representation to the desired output format.
17 //
18 //===----------------------------------------------------------------------===//
19
20 #include "BitcodeReader.h"
21 #include "BitcodeWriter.h"
22 #include "ClangDoc.h"
23 #include "Generators.h"
24 #include "Representation.h"
25 #include "clang/AST/AST.h"
26 #include "clang/AST/Decl.h"
27 #include "clang/ASTMatchers/ASTMatchFinder.h"
28 #include "clang/ASTMatchers/ASTMatchersInternal.h"
29 #include "clang/Driver/Options.h"
30 #include "clang/Frontend/FrontendActions.h"
31 #include "clang/Tooling/AllTUsExecution.h"
32 #include "clang/Tooling/CommonOptionsParser.h"
33 #include "clang/Tooling/Execution.h"
34 #include "clang/Tooling/Tooling.h"
35 #include "llvm/ADT/APFloat.h"
36 #include "llvm/Support/CommandLine.h"
37 #include "llvm/Support/Error.h"
38 #include "llvm/Support/FileSystem.h"
39 #include "llvm/Support/Mutex.h"
40 #include "llvm/Support/Path.h"
41 #include "llvm/Support/Process.h"
42 #include "llvm/Support/Signals.h"
43 #include "llvm/Support/ThreadPool.h"
44 #include "llvm/Support/raw_ostream.h"
45 #include <atomic>
46 #include <string>
47
48 using namespace clang::ast_matchers;
49 using namespace clang::tooling;
50 using namespace clang;
51
52 static llvm::cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
53 static llvm::cl::OptionCategory ClangDocCategory("clang-doc options");
54
55 static llvm::cl::opt<std::string>
56 ProjectName("project-name", llvm::cl::desc("Name of project."),
57 llvm::cl::cat(ClangDocCategory));
58
59 static llvm::cl::opt<bool> IgnoreMappingFailures(
60 "ignore-map-errors",
61 llvm::cl::desc("Continue if files are not mapped correctly."),
62 llvm::cl::init(true), llvm::cl::cat(ClangDocCategory));
63
64 static llvm::cl::opt<std::string>
65 OutDirectory("output",
66 llvm::cl::desc("Directory for outputting generated files."),
67 llvm::cl::init("docs"), llvm::cl::cat(ClangDocCategory));
68
69 static llvm::cl::opt<bool>
70 PublicOnly("public", llvm::cl::desc("Document only public declarations."),
71 llvm::cl::init(false), llvm::cl::cat(ClangDocCategory));
72
73 static llvm::cl::opt<bool> DoxygenOnly(
74 "doxygen",
75 llvm::cl::desc("Use only doxygen-style comments to generate docs."),
76 llvm::cl::init(false), llvm::cl::cat(ClangDocCategory));
77
78 static llvm::cl::list<std::string> UserStylesheets(
79 "stylesheets", llvm::cl::CommaSeparated,
80 llvm::cl::desc("CSS stylesheets to extend the default styles."),
81 llvm::cl::cat(ClangDocCategory));
82
83 static llvm::cl::opt<std::string> SourceRoot("source-root", llvm::cl::desc(R"(
84 Directory where processed files are stored.
85 Links to definition locations will only be
86 generated if the file is in this dir.)"),
87 llvm::cl::cat(ClangDocCategory));
88
89 static llvm::cl::opt<std::string>
90 RepositoryUrl("repository", llvm::cl::desc(R"(
91 URL of repository that hosts code.
92 Used for links to definition locations.)"),
93 llvm::cl::cat(ClangDocCategory));
94
95 enum OutputFormatTy {
96 md,
97 yaml,
98 html,
99 };
100
101 static llvm::cl::opt<OutputFormatTy>
102 FormatEnum("format", llvm::cl::desc("Format for outputted docs."),
103 llvm::cl::values(clEnumValN(OutputFormatTy::yaml, "yaml",
104 "Documentation in YAML format."),
105 clEnumValN(OutputFormatTy::md, "md",
106 "Documentation in MD format."),
107 clEnumValN(OutputFormatTy::html, "html",
108 "Documentation in HTML format.")),
109 llvm::cl::init(OutputFormatTy::yaml),
110 llvm::cl::cat(ClangDocCategory));
111
getFormatString()112 std::string getFormatString() {
113 switch (FormatEnum) {
114 case OutputFormatTy::yaml:
115 return "yaml";
116 case OutputFormatTy::md:
117 return "md";
118 case OutputFormatTy::html:
119 return "html";
120 }
121 llvm_unreachable("Unknown OutputFormatTy");
122 }
123
124 // This function isn't referenced outside its translation unit, but it
125 // can't use the "static" keyword because its address is used for
126 // GetMainExecutable (since some platforms don't support taking the
127 // address of main, and some platforms can't implement GetMainExecutable
128 // without being given the address of a function in the main executable).
GetExecutablePath(const char * Argv0,void * MainAddr)129 std::string GetExecutablePath(const char *Argv0, void *MainAddr) {
130 return llvm::sys::fs::getMainExecutable(Argv0, MainAddr);
131 }
132
CreateDirectory(const Twine & DirName,bool ClearDirectory=false)133 bool CreateDirectory(const Twine &DirName, bool ClearDirectory = false) {
134 std::error_code OK;
135 llvm::SmallString<128> DocsRootPath;
136 if (ClearDirectory) {
137 std::error_code RemoveStatus = llvm::sys::fs::remove_directories(DirName);
138 if (RemoveStatus != OK) {
139 llvm::errs() << "Unable to remove existing documentation directory for "
140 << DirName << ".\n";
141 return true;
142 }
143 }
144 std::error_code DirectoryStatus = llvm::sys::fs::create_directories(DirName);
145 if (DirectoryStatus != OK) {
146 llvm::errs() << "Unable to create documentation directories.\n";
147 return true;
148 }
149 return false;
150 }
151
152 // A function to extract the appropriate file name for a given info's
153 // documentation. The path returned is a composite of the output directory, the
154 // info's relative path and name and the extension. The relative path should
155 // have been constructed in the serialization phase.
156 //
157 // Example: Given the below, the <ext> path for class C will be
158 // <root>/A/B/C.<ext>
159 //
160 // namespace A {
161 // namespace B {
162 //
163 // class C {};
164 //
165 // }
166 // }
getInfoOutputFile(StringRef Root,StringRef RelativePath,StringRef Name,StringRef Ext)167 llvm::Expected<llvm::SmallString<128>> getInfoOutputFile(StringRef Root,
168 StringRef RelativePath,
169 StringRef Name,
170 StringRef Ext) {
171 llvm::SmallString<128> Path;
172 llvm::sys::path::native(Root, Path);
173 llvm::sys::path::append(Path, RelativePath);
174 if (CreateDirectory(Path))
175 return llvm::createStringError(llvm::inconvertibleErrorCode(),
176 "failed to create directory");
177 llvm::sys::path::append(Path, Name + Ext);
178 return Path;
179 }
180
main(int argc,const char ** argv)181 int main(int argc, const char **argv) {
182 llvm::sys::PrintStackTraceOnErrorSignal(argv[0]);
183 std::error_code OK;
184
185 ExecutorName.setInitialValue("all-TUs");
186 auto Exec = clang::tooling::createExecutorFromCommandLineArgs(
187 argc, argv, ClangDocCategory);
188
189 if (!Exec) {
190 llvm::errs() << toString(Exec.takeError()) << "\n";
191 return 1;
192 }
193
194 // Fail early if an invalid format was provided.
195 std::string Format = getFormatString();
196 llvm::outs() << "Emiting docs in " << Format << " format.\n";
197 auto G = doc::findGeneratorByName(Format);
198 if (!G) {
199 llvm::errs() << toString(G.takeError()) << "\n";
200 return 1;
201 }
202
203 ArgumentsAdjuster ArgAdjuster;
204 if (!DoxygenOnly)
205 ArgAdjuster = combineAdjusters(
206 getInsertArgumentAdjuster("-fparse-all-comments",
207 tooling::ArgumentInsertPosition::END),
208 ArgAdjuster);
209
210 clang::doc::ClangDocContext CDCtx = {
211 Exec->get()->getExecutionContext(),
212 ProjectName,
213 PublicOnly,
214 OutDirectory,
215 SourceRoot,
216 RepositoryUrl,
217 {UserStylesheets.begin(), UserStylesheets.end()},
218 {"index.js", "index_json.js"}};
219
220 if (Format == "html") {
221 void *MainAddr = (void *)(intptr_t)GetExecutablePath;
222 std::string ClangDocPath = GetExecutablePath(argv[0], MainAddr);
223 llvm::SmallString<128> AssetsPath;
224 llvm::sys::path::native(ClangDocPath, AssetsPath);
225 AssetsPath = llvm::sys::path::parent_path(AssetsPath);
226 llvm::sys::path::append(AssetsPath, "..", "share", "clang");
227 llvm::SmallString<128> DefaultStylesheet;
228 llvm::sys::path::native(AssetsPath, DefaultStylesheet);
229 llvm::sys::path::append(DefaultStylesheet,
230 "clang-doc-default-stylesheet.css");
231 llvm::SmallString<128> IndexJS;
232 llvm::sys::path::native(AssetsPath, IndexJS);
233 llvm::sys::path::append(IndexJS, "index.js");
234 CDCtx.UserStylesheets.insert(CDCtx.UserStylesheets.begin(),
235 std::string(DefaultStylesheet.str()));
236 CDCtx.FilesToCopy.emplace_back(IndexJS.str());
237 }
238
239 // Mapping phase
240 llvm::outs() << "Mapping decls...\n";
241 auto Err =
242 Exec->get()->execute(doc::newMapperActionFactory(CDCtx), ArgAdjuster);
243 if (Err) {
244 if (IgnoreMappingFailures)
245 llvm::errs() << "Error mapping decls in files. Clang-doc will ignore "
246 "these files and continue:\n"
247 << toString(std::move(Err)) << "\n";
248 else {
249 llvm::errs() << toString(std::move(Err)) << "\n";
250 return 1;
251 }
252 }
253
254 // Collect values into output by key.
255 // In ToolResults, the Key is the hashed USR and the value is the
256 // bitcode-encoded representation of the Info object.
257 llvm::outs() << "Collecting infos...\n";
258 llvm::StringMap<std::vector<StringRef>> USRToBitcode;
259 Exec->get()->getToolResults()->forEachResult(
260 [&](StringRef Key, StringRef Value) {
261 auto R = USRToBitcode.try_emplace(Key, std::vector<StringRef>());
262 R.first->second.emplace_back(Value);
263 });
264
265 // First reducing phase (reduce all decls into one info per decl).
266 llvm::outs() << "Reducing " << USRToBitcode.size() << " infos...\n";
267 std::atomic<bool> Error;
268 Error = false;
269 llvm::sys::Mutex IndexMutex;
270 // ExecutorConcurrency is a flag exposed by AllTUsExecution.h
271 llvm::ThreadPool Pool(llvm::hardware_concurrency(ExecutorConcurrency));
272 for (auto &Group : USRToBitcode) {
273 Pool.async([&]() {
274 std::vector<std::unique_ptr<doc::Info>> Infos;
275
276 for (auto &Bitcode : Group.getValue()) {
277 llvm::BitstreamCursor Stream(Bitcode);
278 doc::ClangDocBitcodeReader Reader(Stream);
279 auto ReadInfos = Reader.readBitcode();
280 if (!ReadInfos) {
281 llvm::errs() << toString(ReadInfos.takeError()) << "\n";
282 Error = true;
283 return;
284 }
285 std::move(ReadInfos->begin(), ReadInfos->end(),
286 std::back_inserter(Infos));
287 }
288
289 auto Reduced = doc::mergeInfos(Infos);
290 if (!Reduced) {
291 llvm::errs() << llvm::toString(Reduced.takeError());
292 return;
293 }
294
295 doc::Info *I = Reduced.get().get();
296 auto InfoPath =
297 getInfoOutputFile(OutDirectory, I->getRelativeFilePath(""),
298 I->getFileBaseName(), "." + Format);
299 if (!InfoPath) {
300 llvm::errs() << toString(InfoPath.takeError()) << "\n";
301 Error = true;
302 return;
303 }
304 std::error_code FileErr;
305 llvm::raw_fd_ostream InfoOS(InfoPath.get(), FileErr,
306 llvm::sys::fs::OF_None);
307 if (FileErr) {
308 llvm::errs() << "Error opening info file " << InfoPath.get() << ": "
309 << FileErr.message() << "\n";
310 return;
311 }
312
313 IndexMutex.lock();
314 // Add a reference to this Info in the Index
315 clang::doc::Generator::addInfoToIndex(CDCtx.Idx, I);
316 IndexMutex.unlock();
317
318 if (auto Err = G->get()->generateDocForInfo(I, InfoOS, CDCtx))
319 llvm::errs() << toString(std::move(Err)) << "\n";
320 });
321 }
322
323 Pool.wait();
324
325 if (Error)
326 return 1;
327
328 llvm::outs() << "Generating assets for docs...\n";
329 Err = G->get()->createResources(CDCtx);
330 if (Err) {
331 llvm::errs() << toString(std::move(Err)) << "\n";
332 return 1;
333 }
334
335 return 0;
336 }
337