clang-tools 8.0.0

ClangDocMain.cpp
Go to the documentation of this file.
1 //===-- ClangDocMain.cpp - ClangDoc -----------------------------*- C++ -*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // This tool for generating C and C++ documenation from source code
11 // and comments. Generally, it runs a LibTooling FrontendAction on source files,
12 // mapping each declaration in those files to its USR and serializing relevant
13 // information into LLVM bitcode. It then runs a pass over the collected
14 // declaration information, reducing by USR. There is an option to dump this
15 // intermediate result to bitcode. Finally, it hands the reduced information
16 // off to a generator, which does the final parsing from the intermediate
17 // representation to the desired output format.
18 //
19 //===----------------------------------------------------------------------===//
20
21 #include "BitcodeReader.h"
22 #include "BitcodeWriter.h"
23 #include "ClangDoc.h"
24 #include "Generators.h"
25 #include "Representation.h"
26 #include "clang/AST/AST.h"
27 #include "clang/AST/Decl.h"
28 #include "clang/ASTMatchers/ASTMatchFinder.h"
29 #include "clang/ASTMatchers/ASTMatchersInternal.h"
30 #include "clang/Driver/Options.h"
31 #include "clang/Frontend/FrontendActions.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/Path.h"
40 #include "llvm/Support/Process.h"
41 #include "llvm/Support/Signals.h"
42 #include "llvm/Support/raw_ostream.h"
43 #include <string>
44
45 using namespace clang::ast_matchers;
46 using namespace clang::tooling;
47 using namespace clang;
48
49 static llvm::cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
50 static llvm::cl::OptionCategory ClangDocCategory("clang-doc options");
51
52 static llvm::cl::opt<std::string>
53 OutDirectory("output",
54 llvm::cl::desc("Directory for outputting generated files."),
55 llvm::cl::init("docs"), llvm::cl::cat(ClangDocCategory));
56
57 static llvm::cl::opt<bool>
58 PublicOnly("public", llvm::cl::desc("Document only public declarations."),
59 llvm::cl::init(false), llvm::cl::cat(ClangDocCategory));
60
61 static llvm::cl::opt<bool> DoxygenOnly(
62 "doxygen",
63 llvm::cl::desc("Use only doxygen-style comments to generate docs."),
64 llvm::cl::init(false), llvm::cl::cat(ClangDocCategory));
65
66 enum OutputFormatTy {
67 md,
68 yaml,
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 llvm::cl::init(OutputFormatTy::yaml),
78 llvm::cl::cat(ClangDocCategory));
79
80 std::string getFormatString() {
81 switch (FormatEnum) {
82 case OutputFormatTy::yaml:
83 return "yaml";
84 case OutputFormatTy::md:
85 return "md";
86 }
87 llvm_unreachable("Unknown OutputFormatTy");
88 }
89
90 bool CreateDirectory(const Twine &DirName, bool ClearDirectory = false) {
91 std::error_code OK;
92 llvm::SmallString<128> DocsRootPath;
93 if (ClearDirectory) {
94 std::error_code RemoveStatus = llvm::sys::fs::remove_directories(DirName);
95 if (RemoveStatus != OK) {
96 llvm::errs() << "Unable to remove existing documentation directory for "
97 << DirName << ".\n";
98 return true;
99 }
100 }
101 std::error_code DirectoryStatus = llvm::sys::fs::create_directories(DirName);
102 if (DirectoryStatus != OK) {
103 llvm::errs() << "Unable to create documentation directories.\n";
104 return true;
105 }
106 return false;
107 }
108
109 // A function to extract the appropriate path name for a given info's
110 // documentation. The path returned is a composite of the parent namespaces as
111 // directories plus the decl name as the filename.
112 //
113 // Example: Given the below, the <ext> path for class C will be <
114 // root>/A/B/C.<ext>
115 //
116 // namespace A {
117 // namesapce B {
118 //
119 // class C {};
120 //
121 // }
122 // }
123 llvm::Expected<llvm::SmallString<128>>
124 getInfoOutputFile(StringRef Root,
125 llvm::SmallVectorImpl<doc::Reference> &Namespaces,
126 StringRef Name, StringRef Ext) {
127 std::error_code OK;
128 llvm::SmallString<128> Path;
129 llvm::sys::path::native(Root, Path);
130 for (auto R = Namespaces.rbegin(), E = Namespaces.rend(); R != E; ++R)
131 llvm::sys::path::append(Path, R->Name);
132
133 if (CreateDirectory(Path))
134 return llvm::make_error<llvm::StringError>("Unable to create directory.\n",
135 llvm::inconvertibleErrorCode());
136
137 if (Name.empty())
138 Name = "GlobalNamespace";
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.
145 bool bitcodeResultsToInfos(
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
226 auto InfoPath =
227 getInfoOutputFile(OutDirectory, I->Namespace, I->Name, "." + Format);
228 if (!InfoPath) {
229 llvm::errs() << toString(InfoPath.takeError()) << "\n";
230 continue;
231 }
232 std::error_code FileErr;
233 llvm::raw_fd_ostream InfoOS(InfoPath.get(), FileErr, llvm::sys::fs::F_None);
234 if (FileErr != OK) {
235 llvm::errs() << "Error opening info file: " << FileErr.message() << "\n";
236 continue;
237 }
238
239 if (auto Err = G->get()->generateDocForInfo(I, InfoOS))
240 llvm::errs() << toString(std::move(Err)) << "\n";
241 }
242
243 return 0;
244 }
clang::ast_matchers
Definition: AbseilMatcher.h:15
Representation.h
clang::doc::Info::Namespace
llvm::SmallVector< Reference, 4 > Namespace
Definition: Representation.h:173
clang::tooling
Definition: ClangTidy.h:28
BitcodeReader.h
clang::tidy::cppcoreguidelines::toString
static llvm::StringRef toString(SpecialMemberFunctionsCheck::SpecialMemberFunctionKind K)
Definition: SpecialMemberFunctionsCheck.cpp:59
Results
std::vector< CodeCompletionResult > Results
Definition: CodeComplete.cpp:702
CreateDirectory
bool CreateDirectory(const Twine &DirName, bool ClearDirectory=false)
Definition: ClangDocMain.cpp:90
md
Definition: ClangDocMain.cpp:67
Generators.h
Path
std::vector< HeaderHandle > Path
Definition: PreprocessorTracker.cpp:538
PublicOnly
static llvm::cl::opt< bool > PublicOnly("public", llvm::cl::desc("Document only public declarations."), llvm::cl::init(false), llvm::cl::cat(ClangDocCategory))
bitcodeResultsToInfos
bool bitcodeResultsToInfos(tooling::ToolResults &Results, llvm::StringMap< std::vector< std::unique_ptr< doc::Info >>> &Output)
Definition: ClangDocMain.cpp:145
getInfoOutputFile
llvm::Expected< llvm::SmallString< 128 > > getInfoOutputFile(StringRef Root, llvm::SmallVectorImpl< doc::Reference > &Namespaces, StringRef Name, StringRef Ext)
Definition: ClangDocMain.cpp:124
clang::doc::findGeneratorByName
llvm::Expected< std::unique_ptr< Generator > > findGeneratorByName(llvm::StringRef Format)
Definition: Generators.cpp:18
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.")), llvm::cl::init(OutputFormatTy::yaml), llvm::cl::cat(ClangDocCategory))
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))
CommonHelp
static llvm::cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage)
main
int main(int argc, const char **argv)
Definition: ClangDocMain.cpp:167
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))
ClangDoc.h
clang::doc::mergeInfos
llvm::Expected< std::unique_ptr< Info > > mergeInfos(std::vector< std::unique_ptr< Info >> &Values)
Definition: Representation.cpp:95
clang::doc::Info::Name
SmallString< 16 > Name
Definition: Representation.h:171
Name
static constexpr llvm::StringLiteral Name
Definition: UppercaseLiteralSuffixCheck.cpp:28
clang::doc::ClangDocBitcodeReader::readBitcode
llvm::Expected< std::vector< std::unique_ptr< Info > > > readBitcode()
Definition: BitcodeReader.cpp:682
getFormatString
std::string getFormatString()
Definition: ClangDocMain.cpp:80
clang::doc::Info
A base struct for Infos.
Definition: Representation.h:157
BitcodeWriter.h
yaml
Definition: ClangDocMain.cpp:68
clang::doc::ClangDocBitcodeReader
Definition: BitcodeReader.h:31
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ChangeNamespace.cpp:18
OutputFormatTy
OutputFormatTy
Definition: ClangDocMain.cpp:66
clang::doc::ClangDocContext
Definition: Representation.h:283
ClangDocCategory
static llvm::cl::OptionCategory ClangDocCategory("clang-doc options")
clang::doc::newMapperActionFactory
std::unique_ptr< tooling::FrontendActionFactory > newMapperActionFactory(ClangDocContext CDCtx)
Definition: ClangDoc.cpp:57