clang-tools  9.0.0
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++ documenation 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/CommonOptionsParser.h"
32 #include "clang/Tooling/Execution.h"
33 #include "clang/Tooling/Tooling.h"
34 #include "llvm/ADT/APFloat.h"
35 #include "llvm/Support/CommandLine.h"
36 #include "llvm/Support/Error.h"
37 #include "llvm/Support/FileSystem.h"
38 #include "llvm/Support/Path.h"
39 #include "llvm/Support/Process.h"
40 #include "llvm/Support/Signals.h"
41 #include "llvm/Support/raw_ostream.h"
42 #include <string>
43 
44 using namespace clang::ast_matchers;
45 using namespace clang::tooling;
46 using namespace clang;
47 
48 static llvm::cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
49 static llvm::cl::OptionCategory ClangDocCategory("clang-doc options");
50 
51 static llvm::cl::opt<std::string>
52  OutDirectory("output",
53  llvm::cl::desc("Directory for outputting generated files."),
54  llvm::cl::init("docs"), llvm::cl::cat(ClangDocCategory));
55 
56 static llvm::cl::opt<bool>
57  PublicOnly("public", llvm::cl::desc("Document only public declarations."),
58  llvm::cl::init(false), llvm::cl::cat(ClangDocCategory));
59 
60 static llvm::cl::opt<bool> DoxygenOnly(
61  "doxygen",
62  llvm::cl::desc("Use only doxygen-style comments to generate docs."),
63  llvm::cl::init(false), llvm::cl::cat(ClangDocCategory));
64 
66  md,
69 };
70 
71 static llvm::cl::opt<OutputFormatTy>
72  FormatEnum("format", llvm::cl::desc("Format for outputted docs."),
73  llvm::cl::values(clEnumValN(OutputFormatTy::yaml, "yaml",
74  "Documentation in YAML format."),
75  clEnumValN(OutputFormatTy::md, "md",
76  "Documentation in MD format."),
77  clEnumValN(OutputFormatTy::html, "html",
78  "Documentation in HTML format.")),
79  llvm::cl::init(OutputFormatTy::yaml),
80  llvm::cl::cat(ClangDocCategory));
81 
82 std::string getFormatString() {
83  switch (FormatEnum) {
85  return "yaml";
86  case OutputFormatTy::md:
87  return "md";
89  return "html";
90  }
91  llvm_unreachable("Unknown OutputFormatTy");
92 }
93 
94 bool CreateDirectory(const Twine &DirName, bool ClearDirectory = false) {
95  std::error_code OK;
96  llvm::SmallString<128> DocsRootPath;
97  if (ClearDirectory) {
98  std::error_code RemoveStatus = llvm::sys::fs::remove_directories(DirName);
99  if (RemoveStatus != OK) {
100  llvm::errs() << "Unable to remove existing documentation directory for "
101  << DirName << ".\n";
102  return true;
103  }
104  }
105  std::error_code DirectoryStatus = llvm::sys::fs::create_directories(DirName);
106  if (DirectoryStatus != OK) {
107  llvm::errs() << "Unable to create documentation directories.\n";
108  return true;
109  }
110  return false;
111 }
112 
113 // A function to extract the appropriate file name for a given info's
114 // documentation. The path returned is a composite of the output directory, the
115 // info's relative path and name and the extension. The relative path should
116 // have been constructed in the serialization phase.
117 //
118 // Example: Given the below, the <ext> path for class C will be
119 // <root>/A/B/C.<ext>
120 //
121 // namespace A {
122 // namesapce B {
123 //
124 // class C {};
125 //
126 // }
127 // }
128 llvm::Expected<llvm::SmallString<128>> getInfoOutputFile(StringRef Root,
129  StringRef RelativePath,
130  StringRef Name,
131  StringRef Ext) {
132  std::error_code OK;
133  llvm::SmallString<128> Path;
134  llvm::sys::path::native(Root, Path);
135  llvm::sys::path::append(Path, RelativePath);
136  if (CreateDirectory(Path))
137  return llvm::make_error<llvm::StringError>("Unable to create directory.\n",
138  llvm::inconvertibleErrorCode());
139  llvm::sys::path::append(Path, Name + Ext);
140  return Path;
141 }
142 
143 // Iterate through tool results and build string map of info vectors from the
144 // encoded bitstreams.
146  tooling::ToolResults &Results,
147  llvm::StringMap<std::vector<std::unique_ptr<doc::Info>>> &Output) {
148  bool Err = false;
149  Results.forEachResult([&](StringRef Key, StringRef Value) {
150  llvm::BitstreamCursor Stream(Value);
151  doc::ClangDocBitcodeReader Reader(Stream);
152  auto Infos = Reader.readBitcode();
153  if (!Infos) {
154  llvm::errs() << toString(Infos.takeError()) << "\n";
155  Err = true;
156  return;
157  }
158  for (auto &I : Infos.get()) {
159  auto R =
160  Output.try_emplace(Key, std::vector<std::unique_ptr<doc::Info>>());
161  R.first->second.emplace_back(std::move(I));
162  }
163  });
164  return Err;
165 }
166 
167 int main(int argc, const char **argv) {
168  llvm::sys::PrintStackTraceOnErrorSignal(argv[0]);
169  std::error_code OK;
170 
171  ExecutorName.setInitialValue("all-TUs");
172  auto Exec = clang::tooling::createExecutorFromCommandLineArgs(
173  argc, argv, ClangDocCategory);
174 
175  if (!Exec) {
176  llvm::errs() << toString(Exec.takeError()) << "\n";
177  return 1;
178  }
179 
180  // Fail early if an invalid format was provided.
181  std::string Format = getFormatString();
182  llvm::outs() << "Emiting docs in " << Format << " format.\n";
183  auto G = doc::findGeneratorByName(Format);
184  if (!G) {
185  llvm::errs() << toString(G.takeError()) << "\n";
186  return 1;
187  }
188 
189  ArgumentsAdjuster ArgAdjuster;
190  if (!DoxygenOnly)
191  ArgAdjuster = combineAdjusters(
192  getInsertArgumentAdjuster("-fparse-all-comments",
193  tooling::ArgumentInsertPosition::END),
194  ArgAdjuster);
195 
196  // Mapping phase
197  llvm::outs() << "Mapping decls...\n";
198  clang::doc::ClangDocContext CDCtx = {Exec->get()->getExecutionContext(),
199  PublicOnly};
200  auto Err =
201  Exec->get()->execute(doc::newMapperActionFactory(CDCtx), ArgAdjuster);
202  if (Err) {
203  llvm::errs() << toString(std::move(Err)) << "\n";
204  return 1;
205  }
206 
207  // Collect values into output by key.
208  // In ToolResults, the Key is the hashed USR and the value is the
209  // bitcode-encoded representation of the Info object.
210  llvm::outs() << "Collecting infos...\n";
211  llvm::StringMap<std::vector<std::unique_ptr<doc::Info>>> USRToInfos;
212  if (bitcodeResultsToInfos(*Exec->get()->getToolResults(), USRToInfos))
213  return 1;
214 
215  // First reducing phase (reduce all decls into one info per decl).
216  llvm::outs() << "Reducing " << USRToInfos.size() << " infos...\n";
217  for (auto &Group : USRToInfos) {
218  auto Reduced = doc::mergeInfos(Group.getValue());
219  if (!Reduced) {
220  llvm::errs() << llvm::toString(Reduced.takeError());
221  continue;
222  }
223 
224  doc::Info *I = Reduced.get().get();
225  auto InfoPath = getInfoOutputFile(OutDirectory, I->Path, I->extractName(),
226  "." + Format);
227  if (!InfoPath) {
228  llvm::errs() << toString(InfoPath.takeError()) << "\n";
229  return 1;
230  }
231  std::error_code FileErr;
232  llvm::raw_fd_ostream InfoOS(InfoPath.get(), FileErr, llvm::sys::fs::F_None);
233  if (FileErr != OK) {
234  llvm::errs() << "Error opening info file: " << FileErr.message() << "\n";
235  continue;
236  }
237 
238  if (auto Err = G->get()->generateDocForInfo(I, InfoOS))
239  llvm::errs() << toString(std::move(Err)) << "\n";
240  }
241 
242  return 0;
243 }
llvm::SmallString< 16 > extractName()
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))
static llvm::StringRef toString(SpecialMemberFunctionsCheck::SpecialMemberFunctionKind K)
std::vector< CodeCompletionResult > Results
bool CreateDirectory(const Twine &DirName, bool ClearDirectory=false)
std::vector< HeaderHandle > Path
static llvm::cl::opt< bool > PublicOnly("public", llvm::cl::desc("Document only public declarations."), llvm::cl::init(false), llvm::cl::cat(ClangDocCategory))
bool bitcodeResultsToInfos(tooling::ToolResults &Results, llvm::StringMap< std::vector< std::unique_ptr< doc::Info >>> &Output)
llvm::Expected< std::unique_ptr< Generator > > findGeneratorByName(llvm::StringRef Format)
Definition: Generators.cpp:17
static llvm::cl::opt< std::string > OutDirectory("output", llvm::cl::desc("Directory for outputting generated files."), llvm::cl::init("docs"), llvm::cl::cat(ClangDocCategory))
static llvm::cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage)
int main(int argc, const char **argv)
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))
llvm::Expected< std::unique_ptr< Info > > mergeInfos(std::vector< std::unique_ptr< Info >> &Values)
static constexpr llvm::StringLiteral Name
llvm::Expected< std::vector< std::unique_ptr< Info > > > readBitcode()
std::string getFormatString()
A base struct for Infos.
llvm::SmallString< 128 > Path
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
llvm::Expected< llvm::SmallString< 128 > > getInfoOutputFile(StringRef Root, StringRef RelativePath, StringRef Name, StringRef Ext)
OutputFormatTy
static llvm::cl::OptionCategory ClangDocCategory("clang-doc options")
std::unique_ptr< tooling::FrontendActionFactory > newMapperActionFactory(ClangDocContext CDCtx)
Definition: ClangDoc.cpp:56