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"
53static llvm::cl::extrahelp
CommonHelp(CommonOptionsParser::HelpMessage);
56static llvm::cl::opt<std::string>
57 ProjectName(
"project-name", llvm::cl::desc(
"Name of project."),
62 llvm::cl::desc(
"Continue if files are not mapped correctly."),
65static llvm::cl::opt<std::string>
67 llvm::cl::desc(
"Directory for outputting generated files."),
70static llvm::cl::opt<bool>
71 PublicOnly(
"public", llvm::cl::desc(
"Document only public declarations."),
76 llvm::cl::desc(
"Use only doxygen-style comments to generate docs."),
80 "stylesheets", llvm::cl::CommaSeparated,
81 llvm::cl::desc(
"CSS stylesheets to extend the default styles."),
86 llvm::cl::desc(
"User supplied asset path to "
87 "override the default css and js files for html output"),
90static llvm::cl::opt<std::string>
SourceRoot(
"source-root", llvm::cl::desc(R
"(
91Directory where processed files are stored.
92Links to definition locations will only be
93generated if the file is in this dir.)"),
96static llvm::cl::opt<std::string>
98URL of repository that hosts code.
99Used for links to definition locations.)"),
108static llvm::cl::opt<OutputFormatTy>
109 FormatEnum(
"format", llvm::cl::desc(
"Format for outputted docs."),
111 "Documentation in YAML format."),
113 "Documentation in MD format."),
115 "Documentation in HTML format.")),
128 llvm_unreachable(
"Unknown OutputFormatTy");
137 return llvm::sys::fs::getMainExecutable(
Argv0, MainAddr);
141 using DirIt = llvm::sys::fs::directory_iterator;
142 std::error_code FileErr;
146 !FileErr && DirStart != DirEnd; DirStart.increment(FileErr)) {
147 FilePath = DirStart->path();
148 if (llvm::sys::fs::is_regular_file(FilePath)) {
149 if (llvm::sys::path::extension(FilePath) ==
".css")
151 std::string(FilePath));
152 else if (llvm::sys::path::extension(FilePath) ==
".js")
153 CDCtx.
JsScripts.emplace_back(FilePath.str());
157 return llvm::createFileError(FilePath, FileErr);
158 return llvm::Error::success();
165 llvm::SmallString<128> NativeClangDocPath;
166 llvm::sys::path::native(ClangDocPath, NativeClangDocPath);
168 llvm::SmallString<128> AssetsPath;
169 AssetsPath = llvm::sys::path::parent_path(NativeClangDocPath);
170 llvm::sys::path::append(AssetsPath,
"..",
"share",
"clang-doc");
171 llvm::SmallString<128> DefaultStylesheet;
172 llvm::sys::path::native(AssetsPath, DefaultStylesheet);
173 llvm::sys::path::append(DefaultStylesheet,
174 "clang-doc-default-stylesheet.css");
175 llvm::SmallString<128> IndexJS;
176 llvm::sys::path::native(AssetsPath, IndexJS);
177 llvm::sys::path::append(IndexJS,
"index.js");
179 if (!llvm::sys::fs::is_regular_file(IndexJS))
180 return llvm::createStringError(llvm::inconvertibleErrorCode(),
181 "default index.js file missing at " +
184 if (!llvm::sys::fs::is_regular_file(DefaultStylesheet))
185 return llvm::createStringError(
186 llvm::inconvertibleErrorCode(),
187 "default clang-doc-default-stylesheet.css file missing at " +
188 DefaultStylesheet +
"\n");
191 std::string(DefaultStylesheet));
194 return llvm::Error::success();
201 llvm::outs() <<
"Asset path supply is not a directory: " <<
UserAssetPath
202 <<
" falling back to default\n";
210void sortUsrToInfo(llvm::StringMap<std::unique_ptr<doc::Info>> &USRToInfo) {
211 for (
auto &I : USRToInfo) {
212 auto &
Info = I.second;
213 if (
Info->IT == doc::InfoType::IT_namespace) {
217 if (
Info->IT == doc::InfoType::IT_record) {
219 Record->Children.sort();
224int main(
int argc,
const char **argv) {
225 llvm::sys::PrintStackTraceOnErrorSignal(argv[0]);
228 const char *Overview =
229 R
"(Generates documentation from source code and comments.
231Example usage for files without flags (default):
233 $ clang-doc File1.cpp File2.cpp ... FileN.cpp
235Example usage for a project using a compile commands database:
237 $ clang-doc --executor=all-TUs compile_commands.json
240 auto Executor = clang::tooling::createExecutorFromCommandLineArgs(
244 llvm::errs() << toString(Executor.takeError()) <<
"\n";
250 llvm::outs() <<
"Emiting docs in " << Format <<
" format.\n";
253 llvm::errs() << toString(G.takeError()) <<
"\n";
257 ArgumentsAdjuster ArgAdjuster;
259 ArgAdjuster = combineAdjusters(
260 getInsertArgumentAdjuster(
"-fparse-all-comments",
261 tooling::ArgumentInsertPosition::END),
265 Executor->get()->getExecutionContext(),
274 if (Format ==
"html") {
276 llvm::errs() << toString(std::move(Err)) <<
"\n";
282 llvm::outs() <<
"Mapping decls...\n";
287 llvm::errs() <<
"Error mapping decls in files. Clang-doc will ignore "
288 "these files and continue:\n"
289 << toString(std::move(Err)) <<
"\n";
291 llvm::errs() << toString(std::move(Err)) <<
"\n";
299 llvm::outs() <<
"Collecting infos...\n";
300 llvm::StringMap<std::vector<StringRef>> USRToBitcode;
301 Executor->get()->getToolResults()->forEachResult(
302 [&](StringRef Key, StringRef Value) {
303 USRToBitcode[
Key].emplace_back(Value);
308 llvm::sys::Mutex USRToInfoMutex;
309 llvm::StringMap<std::unique_ptr<doc::Info>> USRToInfo;
312 llvm::outs() <<
"Reducing " << USRToBitcode.size() <<
" infos...\n";
313 std::atomic<bool>
Error;
315 llvm::sys::Mutex IndexMutex;
317 llvm::DefaultThreadPool Pool(llvm::hardware_concurrency(ExecutorConcurrency));
318 for (
auto &Group : USRToBitcode) {
320 std::vector<std::unique_ptr<doc::Info>> Infos;
321 for (
auto &Bitcode : Group.getValue()) {
322 llvm::BitstreamCursor Stream(Bitcode);
323 doc::ClangDocBitcodeReader Reader(Stream);
324 auto ReadInfos = Reader.readBitcode();
326 llvm::errs() << toString(ReadInfos.takeError()) <<
"\n";
330 std::move(ReadInfos->begin(), ReadInfos->end(),
331 std::back_inserter(Infos));
336 llvm::errs() << llvm::toString(Reduced.takeError());
342 std::lock_guard<llvm::sys::Mutex> Guard(IndexMutex);
348 std::lock_guard<llvm::sys::Mutex> Guard(USRToInfoMutex);
349 USRToInfo[Group.getKey()] = std::move(Reduced.get());
362 if (std::error_code Err = llvm::sys::fs::create_directories(
OutDirectory);
363 Err != std::error_code()) {
364 llvm::errs() <<
"Failed to create directory '" <<
OutDirectory <<
"'\n";
369 llvm::outs() <<
"Generating docs...\n";
371 G->get()->generateDocs(
OutDirectory, std::move(USRToInfo), CDCtx)) {
372 llvm::errs() << toString(std::move(Err)) <<
"\n";
376 llvm::outs() <<
"Generating assets for docs...\n";
377 Err = G->get()->createResources(CDCtx);
379 llvm::outs() <<
"warning: " << toString(std::move(Err)) <<
"\n";
static llvm::cl::opt< std::string > UserAssetPath("asset", llvm::cl::desc("User supplied asset path to " "override the default css and js files for html output"), llvm::cl::cat(ClangDocCategory))
static llvm::cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage)
static llvm::cl::opt< bool > PublicOnly("public", llvm::cl::desc("Document only public declarations."), llvm::cl::init(false), llvm::cl::cat(ClangDocCategory))
std::string getExecutablePath(const char *Argv0, void *MainAddr)
int main(int argc, const char **argv)
llvm::Error getHtmlAssetFiles(const char *Argv0, clang::doc::ClangDocContext &CDCtx)
static llvm::cl::opt< std::string > ProjectName("project-name", llvm::cl::desc("Name of project."), llvm::cl::cat(ClangDocCategory))
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::cl::list< std::string > UserStylesheets("stylesheets", llvm::cl::CommaSeparated, llvm::cl::desc("CSS stylesheets to extend the default styles."), llvm::cl::cat(ClangDocCategory))
llvm::Error getAssetFiles(clang::doc::ClangDocContext &CDCtx)
llvm::Error getDefaultAssetFiles(const char *Argv0, clang::doc::ClangDocContext &CDCtx)
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))
void sortUsrToInfo(llvm::StringMap< std::unique_ptr< doc::Info > > &USRToInfo)
Make the output of clang-doc deterministic by sorting the children of namespaces and records.
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))
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::opt< bool > DoxygenOnly("doxygen", llvm::cl::desc("Use only doxygen-style comments to generate docs."), llvm::cl::init(false), llvm::cl::cat(ClangDocCategory))
static llvm::cl::OptionCategory ClangDocCategory("clang-doc options")
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))
std::string getFormatString()
static constexpr llvm::SourceMgr::DiagKind Error
static void addInfoToIndex(Index &Idx, const doc::Info *Info)
llvm::SmallVector< uint64_t, 1024 > Record
llvm::Expected< std::unique_ptr< Info > > mergeInfos(std::vector< std::unique_ptr< Info > > &Values)
std::unique_ptr< tooling::FrontendActionFactory > newMapperActionFactory(ClangDocContext CDCtx)
llvm::Expected< std::unique_ptr< Generator > > findGeneratorByName(llvm::StringRef Format)
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
std::vector< std::string > UserStylesheets
std::vector< std::string > JsScripts