clang-tools  16.0.0git
ClangDocMain.cpp
Go to the documentation of this file.
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 
112 std::string getFormatString() {
113  switch (FormatEnum) {
115  return "yaml";
116  case OutputFormatTy::md:
117  return "md";
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).
129 std::string GetExecutablePath(const char *Argv0, void *MainAddr) {
130  return llvm::sys::fs::getMainExecutable(Argv0, MainAddr);
131 }
132 
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 // }
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 
181 int main(int argc, const char **argv) {
182  llvm::sys::PrintStackTraceOnErrorSignal(argv[0]);
183  std::error_code OK;
184 
185  const char *Overview =
186  R"(Generates documentation from source code and comments.
187 
188 Example usage for files without flags (default):
189 
190  $ clang-doc File1.cpp File2.cpp ... FileN.cpp
191 
192 Example usage for a project using a compile commands database:
193 
194  $ clang-doc --executor=all-TUs compile_commands.json
195 )";
196 
197  auto Executor = clang::tooling::createExecutorFromCommandLineArgs(
198  argc, argv, ClangDocCategory, Overview);
199 
200  if (!Executor) {
201  llvm::errs() << toString(Executor.takeError()) << "\n";
202  return 1;
203  }
204 
205  // Fail early if an invalid format was provided.
206  std::string Format = getFormatString();
207  llvm::outs() << "Emiting docs in " << Format << " format.\n";
208  auto G = doc::findGeneratorByName(Format);
209  if (!G) {
210  llvm::errs() << toString(G.takeError()) << "\n";
211  return 1;
212  }
213 
214  ArgumentsAdjuster ArgAdjuster;
215  if (!DoxygenOnly)
216  ArgAdjuster = combineAdjusters(
217  getInsertArgumentAdjuster("-fparse-all-comments",
218  tooling::ArgumentInsertPosition::END),
219  ArgAdjuster);
220 
222  Executor->get()->getExecutionContext(),
223  ProjectName,
224  PublicOnly,
225  OutDirectory,
226  SourceRoot,
228  {UserStylesheets.begin(), UserStylesheets.end()},
229  {"index.js", "index_json.js"}};
230 
231  if (Format == "html") {
232  void *MainAddr = (void *)(intptr_t)GetExecutablePath;
233  std::string ClangDocPath = GetExecutablePath(argv[0], MainAddr);
234  llvm::SmallString<128> NativeClangDocPath;
235  llvm::sys::path::native(ClangDocPath, NativeClangDocPath);
236  llvm::SmallString<128> AssetsPath;
237  AssetsPath = llvm::sys::path::parent_path(NativeClangDocPath);
238  llvm::sys::path::append(AssetsPath, "..", "share", "clang");
239  llvm::SmallString<128> DefaultStylesheet;
240  llvm::sys::path::native(AssetsPath, DefaultStylesheet);
241  llvm::sys::path::append(DefaultStylesheet,
242  "clang-doc-default-stylesheet.css");
243  llvm::SmallString<128> IndexJS;
244  llvm::sys::path::native(AssetsPath, IndexJS);
245  llvm::sys::path::append(IndexJS, "index.js");
246  CDCtx.UserStylesheets.insert(CDCtx.UserStylesheets.begin(),
247  std::string(DefaultStylesheet.str()));
248  CDCtx.FilesToCopy.emplace_back(IndexJS.str());
249  }
250 
251  // Mapping phase
252  llvm::outs() << "Mapping decls...\n";
253  auto Err =
254  Executor->get()->execute(doc::newMapperActionFactory(CDCtx), ArgAdjuster);
255  if (Err) {
257  llvm::errs() << "Error mapping decls in files. Clang-doc will ignore "
258  "these files and continue:\n"
259  << toString(std::move(Err)) << "\n";
260  else {
261  llvm::errs() << toString(std::move(Err)) << "\n";
262  return 1;
263  }
264  }
265 
266  // Collect values into output by key.
267  // In ToolResults, the Key is the hashed USR and the value is the
268  // bitcode-encoded representation of the Info object.
269  llvm::outs() << "Collecting infos...\n";
270  llvm::StringMap<std::vector<StringRef>> USRToBitcode;
271  Executor->get()->getToolResults()->forEachResult(
272  [&](StringRef Key, StringRef Value) {
273  auto R = USRToBitcode.try_emplace(Key, std::vector<StringRef>());
274  R.first->second.emplace_back(Value);
275  });
276 
277  // First reducing phase (reduce all decls into one info per decl).
278  llvm::outs() << "Reducing " << USRToBitcode.size() << " infos...\n";
279  std::atomic<bool> Error;
280  Error = false;
281  llvm::sys::Mutex IndexMutex;
282  // ExecutorConcurrency is a flag exposed by AllTUsExecution.h
283  llvm::ThreadPool Pool(llvm::hardware_concurrency(ExecutorConcurrency));
284  for (auto &Group : USRToBitcode) {
285  Pool.async([&]() {
286  std::vector<std::unique_ptr<doc::Info>> Infos;
287 
288  for (auto &Bitcode : Group.getValue()) {
289  llvm::BitstreamCursor Stream(Bitcode);
290  doc::ClangDocBitcodeReader Reader(Stream);
291  auto ReadInfos = Reader.readBitcode();
292  if (!ReadInfos) {
293  llvm::errs() << toString(ReadInfos.takeError()) << "\n";
294  Error = true;
295  return;
296  }
297  std::move(ReadInfos->begin(), ReadInfos->end(),
298  std::back_inserter(Infos));
299  }
300 
301  auto Reduced = doc::mergeInfos(Infos);
302  if (!Reduced) {
303  llvm::errs() << llvm::toString(Reduced.takeError());
304  return;
305  }
306 
307  doc::Info *I = Reduced.get().get();
308  auto InfoPath =
310  I->getFileBaseName(), "." + Format);
311  if (!InfoPath) {
312  llvm::errs() << toString(InfoPath.takeError()) << "\n";
313  Error = true;
314  return;
315  }
316  std::error_code FileErr;
317  llvm::raw_fd_ostream InfoOS(InfoPath.get(), FileErr,
318  llvm::sys::fs::OF_None);
319  if (FileErr) {
320  llvm::errs() << "Error opening info file " << InfoPath.get() << ": "
321  << FileErr.message() << "\n";
322  return;
323  }
324 
325  IndexMutex.lock();
326  // Add a reference to this Info in the Index
328  IndexMutex.unlock();
329 
330  if (auto Err = G->get()->generateDocForInfo(I, InfoOS, CDCtx))
331  llvm::errs() << toString(std::move(Err)) << "\n";
332  });
333  }
334 
335  Pool.wait();
336 
337  if (Error)
338  return 1;
339 
340  llvm::outs() << "Generating assets for docs...\n";
341  Err = G->get()->createResources(CDCtx);
342  if (Err) {
343  llvm::errs() << toString(std::move(Err)) << "\n";
344  return 1;
345  }
346 
347  return 0;
348 }
SourceRoot
static llvm::cl::opt< std::string > SourceRoot("source-root", llvm::cl::desc(R"( Directory where processed files are stored. Links to definition locations will only be generated if the file is in this dir.)"), llvm::cl::cat(ClangDocCategory))
clang::doc::ClangDocContext::Idx
Index Idx
Definition: Representation.h:477
Root
ASTNode Root
Definition: DumpAST.cpp:332
Representation.h
RepositoryUrl
static llvm::cl::opt< std::string > RepositoryUrl("repository", llvm::cl::desc(R"( URL of repository that hosts code. Used for links to definition locations.)"), llvm::cl::cat(ClangDocCategory))
UserStylesheets
static llvm::cl::list< std::string > UserStylesheets("stylesheets", llvm::cl::CommaSeparated, llvm::cl::desc("CSS stylesheets to extend the default styles."), llvm::cl::cat(ClangDocCategory))
clang::ast_matchers
Definition: AbseilMatcher.h:14
BitcodeWriter.h
clang::doc::ClangDocContext::UserStylesheets
std::vector< std::string > UserStylesheets
Definition: Representation.h:472
CreateDirectory
bool CreateDirectory(const Twine &DirName, bool ClearDirectory=false)
Definition: ClangDocMain.cpp:128
CommonHelp
static llvm::cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage)
ClangDoc.h
DoxygenOnly
static llvm::cl::opt< bool > DoxygenOnly("doxygen", llvm::cl::desc("Use only doxygen-style comments to generate docs."), llvm::cl::init(false), llvm::cl::cat(ClangDocCategory))
clang::tooling
Definition: ClangTidy.h:26
PublicOnly
static llvm::cl::opt< bool > PublicOnly("public", llvm::cl::desc("Document only public declarations."), llvm::cl::init(false), llvm::cl::cat(ClangDocCategory))
clang::doc::ClangDocContext
Definition: Representation.h:454
clang::doc::newMapperActionFactory
std::unique_ptr< tooling::FrontendActionFactory > newMapperActionFactory(ClangDocContext CDCtx)
Definition: ClangDoc.cpp:56
html
@ html
Definition: ClangDocMain.cpp:93
IgnoreMappingFailures
static llvm::cl::opt< bool > IgnoreMappingFailures("ignore-map-errors", llvm::cl::desc("Continue if files are not mapped correctly."), llvm::cl::init(true), llvm::cl::cat(ClangDocCategory))
FormatEnum
static llvm::cl::opt< OutputFormatTy > FormatEnum("format", llvm::cl::desc("Format for outputted docs."), llvm::cl::values(clEnumValN(OutputFormatTy::yaml, "yaml", "Documentation in YAML format."), clEnumValN(OutputFormatTy::md, "md", "Documentation in MD format."), clEnumValN(OutputFormatTy::html, "html", "Documentation in HTML format.")), llvm::cl::init(OutputFormatTy::yaml), llvm::cl::cat(ClangDocCategory))
Name
Token Name
Definition: MacroToEnumCheck.cpp:89
Argv0
const char * Argv0
Definition: Modularize.cpp:332
GetExecutablePath
std::string GetExecutablePath(const char *Argv0, void *MainAddr)
Definition: ClangDocMain.cpp:124
OutDirectory
static llvm::cl::opt< std::string > OutDirectory("output", llvm::cl::desc("Directory for outputting generated files."), llvm::cl::init("docs"), llvm::cl::cat(ClangDocCategory))
getFormatString
std::string getFormatString()
Definition: ClangDocMain.cpp:107
clang::doc::Info
A base struct for Infos.
Definition: Representation.h:243
clang::doc::Generator::addInfoToIndex
static void addInfoToIndex(Index &Idx, const doc::Info *Info)
Definition: Generators.cpp:59
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
ClangDocCategory
static llvm::cl::OptionCategory ClangDocCategory("clang-doc options")
clang::tidy::cppcoreguidelines::toString
static llvm::StringRef toString(SpecialMemberFunctionsCheck::SpecialMemberFunctionKind K)
Definition: SpecialMemberFunctionsCheck.cpp:55
md
@ md
Definition: ClangDocMain.cpp:91
main
int main(int argc, const char **argv)
Definition: ClangDocMain.cpp:176
Generators.h
ProjectName
static llvm::cl::opt< std::string > ProjectName("project-name", llvm::cl::desc("Name of project."), llvm::cl::cat(ClangDocCategory))
getInfoOutputFile
llvm::Expected< llvm::SmallString< 128 > > getInfoOutputFile(StringRef Root, StringRef RelativePath, StringRef Name, StringRef Ext)
Definition: ClangDocMain.cpp:162
clang::doc::findGeneratorByName
llvm::Expected< std::unique_ptr< Generator > > findGeneratorByName(llvm::StringRef Format)
Definition: Generators.cpp:17
clang::doc::ClangDocContext::FilesToCopy
std::vector< std::string > FilesToCopy
Definition: Representation.h:476
OutputFormatTy
OutputFormatTy
Definition: ClangDocMain.cpp:90
clang::doc::mergeInfos
llvm::Expected< std::unique_ptr< Info > > mergeInfos(std::vector< std::unique_ptr< Info >> &Values)
Definition: Representation.cpp:109
BitcodeReader.h
clang::clangd::MessageType::Error
@ Error
An error message.
clang::doc::Info::getRelativeFilePath
llvm::SmallString< 64 > getRelativeFilePath(const StringRef &CurrentPath) const
Returns the file path for this Info relative to CurrentPath.
Definition: Representation.cpp:166
yaml
@ yaml
Definition: ClangDocMain.cpp:92
Path
std::vector< HeaderHandle > Path
Definition: PreprocessorTracker.cpp:525
clang::doc::Info::getFileBaseName
llvm::SmallString< 16 > getFileBaseName() const
Returns the basename that should be used for this Info.
Definition: Representation.cpp:170