[clang-doc] Use DiagnosticsEngine to handle diagnostic output

Right now we use a combination of outs() and errs() to handle tool output. Instead, we can use existing diagnostic support in clang and LLVM to ensure our tool has a consistent behavior with other tools.

Author: ilovepi

clang-tools-extra/clang-doc/BitcodeReader.cpp

@@ -9,13 +9,16 @@
 #include "BitcodeReader.h"
 #include "llvm/ADT/IndexedMap.h"
 #include "llvm/Support/Error.h"
+#include "llvm/Support/ErrorHandling.h"
 #include "llvm/Support/TimeProfiler.h"
 #include "llvm/Support/raw_ostream.h"
 #include <optional>
 
 namespace clang {
 namespace doc {
 
+static llvm::ExitOnError ExitOnErr("clang-doc error: ");
+
 using Record = llvm::SmallVector<uint64_t, 1024>;
 
 // This implements decode for SmallString.
@@ -717,8 +720,8 @@ llvm::Error addReference(FriendInfo *Friend, Reference &&R, FieldId F) {
 
 template <typename T, typename ChildInfoType>
 static void addChild(T I, ChildInfoType &&R) {
- llvm::errs() << "invalid child type for info";
- exit(1);
+ ExitOnErr(llvm::createStringError(llvm::inconvertibleErrorCode(),
+  "invalid child type for info"));
 }
 
 // Namespace children:
@@ -767,8 +770,9 @@ template <> void addChild(BaseRecordInfo *I, FunctionInfo &&R) {
 // parameters) or TemplateSpecializationInfo (for the specialization's
 // parameters).
 template <typename T> static void addTemplateParam(T I, TemplateParamInfo &&P) {
- llvm::errs() << "invalid container for template parameter";
- exit(1);
+ ExitOnErr(
+ llvm::createStringError(llvm::inconvertibleErrorCode(),
+ "invalid container for template parameter"));
 }
 template <> void addTemplateParam(TemplateInfo *I, TemplateParamInfo &&P) {
  I->Params.emplace_back(std::move(P));
@@ -780,8 +784,8 @@ void addTemplateParam(TemplateSpecializationInfo *I, TemplateParamInfo &&P) {
 
 // Template info. These apply to either records or functions.
 template <typename T> static void addTemplate(T I, TemplateInfo &&P) {
- llvm::errs() << "invalid container for template info";
- exit(1);
+ ExitOnErr(llvm::createStringError(llvm::inconvertibleErrorCode(),
+  "invalid container for template info"));
 }
 template <> void addTemplate(RecordInfo *I, TemplateInfo &&P) {
  I->Template.emplace(std::move(P));
@@ -799,8 +803,9 @@ template <> void addTemplate(FriendInfo *I, TemplateInfo &&P) {
 // Template specializations go only into template records.
 template <typename T>
 static void addTemplateSpecialization(T I, TemplateSpecializationInfo &&TSI) {
- llvm::errs() << "invalid container for template specialization info";
- exit(1);
+ ExitOnErr(llvm::createStringError(
+ llvm::inconvertibleErrorCode(),
+ "invalid container for template specialization info"));
 }
 template <>
 void addTemplateSpecialization(TemplateInfo *I,
@@ -809,8 +814,8 @@ void addTemplateSpecialization(TemplateInfo *I,
 }
 
 template <typename T> static void addConstraint(T I, ConstraintInfo &&C) {
- llvm::errs() << "invalid container for constraint info";
- exit(1);
+ ExitOnErr(llvm::createStringError(llvm::inconvertibleErrorCode(),
+  "invalid container for constraint info"));
 }
 template <> void addConstraint(TemplateInfo *I, ConstraintInfo &&C) {
  I->Constraints.emplace_back(std::move(C));

clang-tools-extra/clang-doc/BitcodeReader.h

@@ -29,7 +29,8 @@ namespace doc {
 // Class to read bitstream into an InfoSet collection
 class ClangDocBitcodeReader {
 public:
- ClangDocBitcodeReader(llvm::BitstreamCursor &Stream) : Stream(Stream) {}
+ ClangDocBitcodeReader(llvm::BitstreamCursor &Stream, DiagnosticsEngine &Diags)
+ : Stream(Stream), Diags(Diags) {}
 
  // Main entry point, calls readBlock to read each block in the given stream.
  llvm::Expected<std::vector<std::unique_ptr<Info>>> readBitcode();
@@ -74,6 +75,7 @@ class ClangDocBitcodeReader {
  llvm::BitstreamCursor &Stream;
  std::optional<llvm::BitstreamBlockInfo> BlockInfo;
  FieldId CurrentReferenceField;
+ DiagnosticsEngine &Diags;
 };
 
 } // namespace doc

clang-tools-extra/clang-doc/BitcodeWriter.cpp

@@ -769,7 +769,9 @@ bool ClangDocBitcodeWriter::dispatchInfoForWrite(Info *I) {
  emitBlock(*static_cast<FriendInfo *>(I));
  break;
  case InfoType::IT_default:
- llvm::errs() << "Unexpected info, unable to write.\n";
+ unsigned ID = Diags.getCustomDiagID(DiagnosticsEngine::Error,
+ "Unexpected info, unable to write.");
+ Diags.Report(ID);
  return true;
  }
  return false;

clang-tools-extra/clang-doc/BitcodeWriter.h

@@ -17,6 +17,7 @@
 
 #include "Representation.h"
 #include "clang/AST/AST.h"
+#include "clang/Basic/Diagnostic.h"
 #include "llvm/ADT/DenseMap.h"
 #include "llvm/ADT/SmallVector.h"
 #include "llvm/ADT/StringRef.h"
@@ -179,7 +180,8 @@ enum class FieldId {
 
 class ClangDocBitcodeWriter {
 public:
- ClangDocBitcodeWriter(llvm::BitstreamWriter &Stream) : Stream(Stream) {
+ ClangDocBitcodeWriter(llvm::BitstreamWriter &Stream, DiagnosticsEngine &Diags)
+ : Stream(Stream), Diags(Diags) {
  emitHeader();
  emitBlockInfoBlock();
  emitVersionBlock();
@@ -264,6 +266,7 @@ class ClangDocBitcodeWriter {
  SmallVector<uint32_t, BitCodeConstants::RecordSize> Record;
  llvm::BitstreamWriter &Stream;
  AbbreviationMap Abbrevs;
+ DiagnosticsEngine &Diags;
 };
 
 } // namespace doc

clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp

@@ -15,6 +15,7 @@
 #include "Generators.h"
 #include "Representation.h"
 #include "support/File.h"
+#include "clang/Basic/Diagnostic.h"
 #include "llvm/Support/Error.h"
 #include "llvm/Support/MemoryBuffer.h"
 #include "llvm/Support/Mustache.h"
@@ -187,11 +188,13 @@ Error MustacheHTMLGenerator::generateDocs(
  }
 
  auto File = MemoryBuffer::getFile(Path);
- if (EC = File.getError(); EC)
- // TODO: Buffer errors to report later, look into using Clang
- // diagnostics.
- llvm::errs() << "Failed to open file: " << Path << " " << EC.message()
- << '\n';
+ if (EC = File.getError(); EC) {
+ unsigned ID = CDCtx.Diags.getCustomDiagID(DiagnosticsEngine::Warning,
+ "Failed to open file: %0 %1");
+ CDCtx.Diags.Report(ID) << Path << EC.message();
+ JSONIter.increment(EC);
+ continue;
+ }
 
  auto Parsed = json::parse((*File)->getBuffer());
  if (!Parsed)

clang-tools-extra/clang-doc/Mapper.cpp

@@ -95,10 +95,10 @@ bool MapASTVisitor::mapDecl(const T *D, bool IsDefinition) {
  // this decl for some reason (e.g. we're only reporting public decls).
  if (Child)
  CDCtx.ECtx->reportResult(llvm::toHex(llvm::toStringRef(Child->USR)),
- serialize::serialize(Child));
+ serialize::serialize(Child, CDCtx.Diags));
  if (Parent)
  CDCtx.ECtx->reportResult(llvm::toHex(llvm::toStringRef(Parent->USR)),
- serialize::serialize(Parent));
+ serialize::serialize(Parent, CDCtx.Diags));
  }
  return true;
 }

clang-tools-extra/clang-doc/Representation.cpp

@@ -481,10 +481,11 @@ ClangDocContext::ClangDocContext(tooling::ExecutionContext *ECtx,
  StringRef RepositoryUrl,
  StringRef RepositoryLinePrefix, StringRef Base,
  std::vector<std::string> UserStylesheets,
+ clang::DiagnosticsEngine &Diags,
  bool FTimeTrace)
- : ECtx(ECtx), ProjectName(ProjectName), PublicOnly(PublicOnly),
- FTimeTrace(FTimeTrace), OutDirectory(OutDirectory),
- UserStylesheets(UserStylesheets), Base(Base) {
+ : ECtx(ECtx), ProjectName(ProjectName), OutDirectory(OutDirectory),
+ SourceRoot(std::string(SourceRoot)), UserStylesheets(UserStylesheets),
+ Base(Base), Diags(Diags), PublicOnly(PublicOnly), FTimeTrace(FTimeTrace) {
  llvm::SmallString<128> SourceRootDir(SourceRoot);
  if (SourceRoot.empty())
  // If no SourceRoot was provided the current path is used as the default

clang-tools-extra/clang-doc/Representation.h

@@ -15,6 +15,7 @@
 #define LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_REPRESENTATION_H
 
 #include "clang/AST/Type.h"
+#include "clang/Basic/Diagnostic.h"
 #include "clang/Basic/Specifiers.h"
 #include "clang/Tooling/StandaloneExecution.h"
 #include "llvm/ADT/APSInt.h"
@@ -600,17 +601,13 @@ llvm::Expected<std::unique_ptr<Info>>
 mergeInfos(std::vector<std::unique_ptr<Info>> &Values);
 
 struct ClangDocContext {
- ClangDocContext() = default;
  ClangDocContext(tooling::ExecutionContext *ECtx, StringRef ProjectName,
  bool PublicOnly, StringRef OutDirectory, StringRef SourceRoot,
  StringRef RepositoryUrl, StringRef RepositoryCodeLinePrefix,
  StringRef Base, std::vector<std::string> UserStylesheets,
- bool FTimeTrace = false);
+ clang::DiagnosticsEngine &Diags, bool FTimeTrace = false);
  tooling::ExecutionContext *ECtx;
- std::string ProjectName; // Name of project clang-doc is documenting.
- bool PublicOnly; // Indicates if only public declarations are documented.
- bool FTimeTrace; // Indicates if ftime trace is turned on
- int Granularity; // Granularity of ftime trace
+ std::string ProjectName; // Name of project clang-doc is documenting.
  std::string OutDirectory; // Directory for outputting generated files.
  std::string SourceRoot; // Directory where processed files are stored. Links
  // to definition locations will only be generated if
@@ -629,7 +626,12 @@ struct ClangDocContext {
  // Maps mustache template types to specific mustache template files.
  // Ex. comment-template -> /path/to/comment-template.mustache
  llvm::StringMap<std::string> MustacheTemplates;
+ // A pointer to a DiagnosticsEngine for error reporting.
+ clang::DiagnosticsEngine &Diags;
  Index Idx;
+ int Granularity; // Granularity of ftime trace
+ bool PublicOnly; // Indicates if only public declarations are documented.
+ bool FTimeTrace; // Indicates if ftime trace is turned on
 };
 
 } // namespace doc

clang-tools-extra/clang-doc/Serialize.cpp

@@ -335,28 +335,29 @@ static std::string getSourceCode(const Decl *D, const SourceRange &R) {
  .str();
 }
 
-template <typename T> static std::string serialize(T &I) {
+template <typename T>
+static std::string serialize(T &I, DiagnosticsEngine &Diags) {
  SmallString<2048> Buffer;
  llvm::BitstreamWriter Stream(Buffer);
- ClangDocBitcodeWriter Writer(Stream);
+ ClangDocBitcodeWriter Writer(Stream, Diags);
  Writer.emitBlock(I);
  return Buffer.str().str();
 }
 
-std::string serialize(std::unique_ptr<Info> &I) {
+std::string serialize(std::unique_ptr<Info> &I, DiagnosticsEngine &Diags) {
  switch (I->IT) {
  case InfoType::IT_namespace:
- return serialize(*static_cast<NamespaceInfo *>(I.get()));
+ return serialize(*static_cast<NamespaceInfo *>(I.get()), Diags);
  case InfoType::IT_record:
- return serialize(*static_cast<RecordInfo *>(I.get()));
+ return serialize(*static_cast<RecordInfo *>(I.get()), Diags);
  case InfoType::IT_enum:
- return serialize(*static_cast<EnumInfo *>(I.get()));
+ return serialize(*static_cast<EnumInfo *>(I.get()), Diags);
  case InfoType::IT_function:
- return serialize(*static_cast<FunctionInfo *>(I.get()));
+ return serialize(*static_cast<FunctionInfo *>(I.get()), Diags);
  case InfoType::IT_concept:
- return serialize(*static_cast<ConceptInfo *>(I.get()));
+ return serialize(*static_cast<ConceptInfo *>(I.get()), Diags);
  case InfoType::IT_variable:
- return serialize(*static_cast<VarInfo *>(I.get()));
+ return serialize(*static_cast<VarInfo *>(I.get()), Diags);
  case InfoType::IT_friend:
  case InfoType::IT_typedef:
  case InfoType::IT_default:

clang-tools-extra/clang-doc/Serialize.h

@@ -83,7 +83,7 @@ emitInfo(const VarDecl *D, const FullComment *FC, const Location &Loc,
 // memory (vs storing USRs directly).
 SymbolID hashUSR(llvm::StringRef USR);
 
-std::string serialize(std::unique_ptr<Info> &I);
+std::string serialize(std::unique_ptr<Info> &I, DiagnosticsEngine &Diags);
 
 } // namespace serialize
 } // namespace doc