Add documentation URL records to the .dia format and expose them via libclang

[owenv]

Summary

A documentation URL is attached to a diagnostic and links to local or remote documentation. The
documentation can then be displayed alongside emitted diagnostics to teach users
about relevant language concepts or describe common problems and solutions.

This commit adds records for serializing documentation URLs in .dia files and
adds support for retrieving them from deserialized diagnostics via libclang.
It does not add any mechanisms for emitting documentation URLs alongside Clang
diagnostics. For now, only downstream projects (swift) support diagnostics
with documentation URLs.

This change is intended to support Swift's "educational notes" feature
(https://github.com/apple/swift/blob/master/docs/Diagnostics.md#educational-notes),
as well as future improvements to Clang's diagnostics. A brief discussion of
the goal behind this change can be found here:
http://lists.llvm.org/pipermail/cfe-dev/2020-May/065475.html

[owenv]

Updated terminology to generalize the feature so Clang diagnostics can adopt it in the future.
Also switched from local paths to URLs so local and remote documentation can both be supported if desired

[owenv]

Reviewers added are a best guess based on arc cover. Sorry if I made a mistake, it's my first time contributing to LLVM!

[gribozavr2]

+ Argyrios for libclang changes.

[jkorous]

Hi Owen,
Do you plan to land the functionality for emitting documentation URLs in clang too?

clang/lib/Frontend/SerializedDiagnosticReader.cpp

323

I am just wondering what happens with the ID. Shouldn't we pass it too?

clang/test/Misc/serialized-diags-doumentation.c

4 ↗

(On Diff #265294)

Tip - you can use regexes in CHECKs.
https://llvm.org/docs/CommandGuide/FileCheck.html#filecheck-regex-matching-syntax

I think we should change this to something like:

// CHECK: [Documentation URL: {{.*}}/doc/swift/diagnostics/nominal-types.md]

[owenv]

• Update a few comments
• Simplify test case

[owenv]

@jkorous I'd like to add support for urls in clang-emitted diagnostics too, but I can't really commit to a timeframe for getting that done atm. I'm hoping to have some time to work on it in the next few weeks.

clang/lib/Frontend/SerializedDiagnosticReader.cpp

323

I think the ID should be Record[0] in the call t visitDocumentationURLRecord below. I based this on the handling of category records.

[owenv]

clang/lib/Frontend/SerializedDiagnosticReader.cpp

323

Sorry, I don't know how to reply without marking this as done

[jkorous]

clang/lib/Frontend/SerializedDiagnosticReader.cpp

323

Got it!

clang/include/clang-c/Index.h

  *
  * \returns A string containing text that should be replace the source
  * code indicated by the \c ReplacementRange.
  */
 CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(
     CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange);
 
 /**
+ * Retrieve the documentation URLs associated with the given diagnostic.
+ *
+ * Linked documentation is intended to be displayed alongside emitted
+ * diagnostics to teach users about relevant language concepts or describe
+ * common problems and solutions when encountering errors.
+ *
+ * \param Diagnostic The diagnostic whose documentation URLs are being queried.
+ *
+ * \returns A set of strings which represent URLs to external documentation.
+ */
+CINDEX_LINKAGE CXStringSet *
+clang_getDiagnosticDocumentationURLs(CXDiagnostic Diagnostic);
+
+/**
  * @}
  */
 
 /**
  * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation
  *
  * The routines in this group provide the ability to create and destroy
  * translation units from files, either by parsing the contents of the files or

clang/include/clang/Frontend/SerializedDiagnosticReader.h

protected:
   }
 
   /// Visit a source range.
   virtual std::error_code visitSourceRangeRecord(const Location &Start,
                                                  const Location &End) {
     return {};
   }
 
+  /// Visit a diagnostic documentation URL.
+  virtual std::error_code visitDocumentationURLRecord(unsigned ID,
+                                                      StringRef Path) {
+    return {};
+  }
+  virtual std::error_code visitDocumentationRecord(unsigned ID) { return {}; }
+
   /// Visit the version of the set of diagnostics.
   virtual std::error_code visitVersionRecord(unsigned Version) { return {}; }
 };
 
 } // namespace serialized_diags
 } // namespace clang
 
 namespace std {
 
 template <>
 struct is_error_code_enum<clang::serialized_diags::SDError> : std::true_type {};
 
 } // namespace std
 
 #endif // LLVM_CLANG_FRONTEND_SERIALIZEDDIAGNOSTICREADER_H

clang/include/clang/Frontend/SerializedDiagnostics.h

 enum RecordIDs {
   RECORD_VERSION = 1,
   RECORD_DIAG,
   RECORD_SOURCE_RANGE,
   RECORD_DIAG_FLAG,
   RECORD_CATEGORY,
   RECORD_FILENAME,
   RECORD_FIXIT,
+  RECORD_DOCUMENTATION_URL,
+  RECORD_DOCUMENTATION,
   RECORD_FIRST = RECORD_VERSION,
-  RECORD_LAST = RECORD_FIXIT
+  RECORD_LAST = RECORD_DOCUMENTATION
 };
 
 /// A stable version of DiagnosticIDs::Level.
 ///
 /// Do not change the order of values in this enum, and please increment the
 /// serialized diagnostics version number when you add to it.
 enum Level {
   Ignored = 0,

clang/lib/Frontend/SerializedDiagnosticPrinter.cpp

 
 typedef llvm::DenseMap<unsigned, unsigned> AbbrevLookup;
 
 class SDiagsMerger : SerializedDiagnosticReader {
   SDiagsWriter &Writer;
   AbbrevLookup FileLookup;
   AbbrevLookup CategoryLookup;
   AbbrevLookup DiagFlagLookup;
+  AbbrevLookup DocumentationLookup;
 
 public:
   SDiagsMerger(SDiagsWriter &Writer)
       : SerializedDiagnosticReader(), Writer(Writer) {}
 
   std::error_code mergeRecordsFromFile(const char *File) {
     return readDiagnostics(File);
   }
std::error_code visitFilenameRecord(unsigned ID, unsigned Size,
                                       StringRef Name) override;
   std::error_code visitFixitRecord(const serialized_diags::Location &Start,
                                    const serialized_diags::Location &End,
                                    StringRef CodeToInsert) override;
   std::error_code
   visitSourceRangeRecord(const serialized_diags::Location &Start,
                          const serialized_diags::Location &End) override;
 
+  std::error_code visitDocumentationURLRecord(unsigned ID,
+                                              StringRef URL) override;
+  std::error_code visitDocumentationRecord(unsigned ID) override;
+
 private:
   std::error_code adjustSourceLocFilename(RecordData &Record,
                                           unsigned int offset);
 
   void adjustAbbrevID(RecordData &Record, AbbrevLookup &Lookup,
                       unsigned NewAbbrev);
 
   void writeRecordWithAbbrev(unsigned ID, RecordData &Record);
void EmitDiagnosticMessage(FullSourceLoc Loc, PresumedLoc PLoc,
                              DiagnosticsEngine::Level Level, StringRef Message,
                              DiagOrStoredDiag D);
 
   /// Emit FIXIT and SOURCE_RANGE records for a diagnostic.
   void EmitCodeContext(SmallVectorImpl<CharSourceRange> &Ranges,
                        ArrayRef<FixItHint> Hints,
                        const SourceManager &SM);
 
+  /// Emit record(s) for diagnostic documentation URLs.
+  void EmitDocumentation(ArrayRef<StringRef> URLs);
+
   /// Emit a record for a CharSourceRange.
   void EmitCharSourceRange(CharSourceRange R, const SourceManager &SM);
 
   /// Emit the string information for the category.
   unsigned getEmitCategory(unsigned category = 0);
 
   /// Emit the string information for diagnostic flags.
   unsigned getEmitDiagnosticFlag(DiagnosticsEngine::Level DiagLevel,
                                  unsigned DiagID = 0);
 
   unsigned getEmitDiagnosticFlag(StringRef DiagName);
 
   /// Emit (lazily) the file string and retrieved the file identifier.
   unsigned getEmitFile(const char *Filename);
 
+  /// Lazily emit a diagnostic documentation URL.
+  unsigned getEmitDocumentationURL(StringRef URL);
+
   /// Add SourceLocation information the specified record.
   void AddLocToRecord(FullSourceLoc Loc, PresumedLoc PLoc,
                       RecordDataImpl &Record, unsigned TokSize = 0);
 
   /// Add SourceLocation information the specified record.
   void AddLocToRecord(FullSourceLoc Loc, RecordDataImpl &Record,
                       unsigned TokSize = 0) {
     AddLocToRecord(Loc, Loc.hasManager() ? Loc.getPresumedLoc() : PresumedLoc(),
struct SharedState {
     SmallString<256> diagBuf;
 
     /// The collection of diagnostic categories used.
     llvm::DenseSet<unsigned> Categories;
 
     /// The collection of files used.
     llvm::DenseMap<const char *, unsigned> Files;
 
+    /// The collection of documentation URLs used.
+    llvm::DenseMap<const char *, unsigned> DocumentationURLs;
+
     typedef llvm::DenseMap<const void *, std::pair<unsigned, StringRef> >
     DiagFlagsTy;
 
     /// Map for uniquing strings.
     DiagFlagsTy DiagFlags;
 
     /// Whether we have already started emission of any DIAG blocks. Once
     /// this becomes \c true, we never close a DIAG block until we know that we're
void SDiagsWriter::EmitBlockInfoBlock() {
 
   EmitBlockID(BLOCK_DIAG, "Diag", Stream, Record);
   EmitRecordID(RECORD_DIAG, "DiagInfo", Stream, Record);
   EmitRecordID(RECORD_SOURCE_RANGE, "SrcRange", Stream, Record);
   EmitRecordID(RECORD_CATEGORY, "CatName", Stream, Record);
   EmitRecordID(RECORD_DIAG_FLAG, "DiagFlag", Stream, Record);
   EmitRecordID(RECORD_FILENAME, "FileName", Stream, Record);
   EmitRecordID(RECORD_FIXIT, "FixIt", Stream, Record);
+  EmitRecordID(RECORD_DOCUMENTATION_URL, "DocumentationURL", Stream, Record);
+  EmitRecordID(RECORD_DOCUMENTATION_URL, "Documentation", Stream, Record);
 
   // Emit abbreviation for RECORD_DIAG.
   Abbrev = std::make_shared<BitCodeAbbrev>();
   Abbrev->Add(BitCodeAbbrevOp(RECORD_DIAG));
   Abbrev->Add(BitCodeAbbrevOp(BitCodeAbbrevOp::Fixed, 3));  // Diag level.
   AddSourceLocationAbbrev(*Abbrev);
   Abbrev->Add(BitCodeAbbrevOp(BitCodeAbbrevOp::Fixed, 10)); // Category.
   Abbrev->Add(BitCodeAbbrevOp(BitCodeAbbrevOp::Fixed, 10)); // Mapped Diag ID.
void SDiagsWriter::EmitBlockInfoBlock() {
   Abbrev = std::make_shared<BitCodeAbbrev>();
   Abbrev->Add(BitCodeAbbrevOp(RECORD_FIXIT));
   AddRangeLocationAbbrev(*Abbrev);
   Abbrev->Add(BitCodeAbbrevOp(BitCodeAbbrevOp::Fixed, 16)); // Text size.
   Abbrev->Add(BitCodeAbbrevOp(BitCodeAbbrevOp::Blob));      // FixIt text.
   Abbrevs.set(RECORD_FIXIT, Stream.EmitBlockInfoAbbrev(BLOCK_DIAG,
                                                        Abbrev));
 
+  // Emit the abbreviation for RECORD_DOCUMENTATION_URL.
+  Abbrev = std::make_shared<BitCodeAbbrev>();
+  Abbrev->Add(BitCodeAbbrevOp(RECORD_DOCUMENTATION_URL));
+  Abbrev->Add(BitCodeAbbrevOp(BitCodeAbbrevOp::Fixed, 10)); // Mapped doc ID.
+  Abbrev->Add(BitCodeAbbrevOp(BitCodeAbbrevOp::Fixed, 16)); // URL size.
+  Abbrev->Add(BitCodeAbbrevOp(BitCodeAbbrevOp::Blob));      // URL text.
+  Abbrevs.set(RECORD_DOCUMENTATION_URL,
+              Stream.EmitBlockInfoAbbrev(BLOCK_DIAG, Abbrev));
+
+  // Emit the abbreviation for RECORD_DOCUMENTATION.
+  Abbrev = std::make_shared<BitCodeAbbrev>();
+  Abbrev->Add(BitCodeAbbrevOp(RECORD_DOCUMENTATION));
+  Abbrev->Add(
+      BitCodeAbbrevOp(BitCodeAbbrevOp::Fixed, 10)); // Mapped doc note ID.
+  Abbrevs.set(RECORD_DOCUMENTATION,
+              Stream.EmitBlockInfoAbbrev(BLOCK_DIAG, Abbrev));
+
   Stream.ExitBlock();
 }
 
 void SDiagsWriter::EmitMetaBlock() {
   llvm::BitstreamWriter &Stream = State->Stream;
   AbbreviationMap &Abbrevs = State->Abbrevs;
 
   Stream.EnterSubblock(BLOCK_META, 3);
RecordData::value_type Record[] = {RECORD_DIAG_FLAG, entry.first,
                                        FlagName.size()};
     State->Stream.EmitRecordWithBlob(State->Abbrevs.get(RECORD_DIAG_FLAG),
                                      Record, FlagName);
   }
 
   return entry.first;
 }
 
+unsigned SDiagsWriter::getEmitDocumentationURL(StringRef URL) {
+  if (URL.empty())
+    return 0;
+
+  unsigned &entry = State->DocumentationURLs[URL.data()];
+  if (entry)
+    return entry;
+
+  // Lazily generate the record for the URL.
+  entry = State->DocumentationURLs.size();
+  RecordData::value_type Record[] = {RECORD_DOCUMENTATION_URL, entry,
+                                     URL.size()};
+  State->Stream.EmitRecordWithBlob(State->Abbrevs.get(RECORD_DOCUMENTATION_URL),
+                                   Record, URL);
+
+  return entry;
+}
+
 void SDiagsWriter::HandleDiagnostic(DiagnosticsEngine::Level DiagLevel,
                                     const Diagnostic &Info) {
   // Enter the block for a non-note diagnostic immediately, rather than waiting
   // for beginDiagnostic, in case associated notes are emitted before we get
   // there.
   if (DiagLevel != DiagnosticsEngine::Note) {
     if (State->EmittedAnyDiagBlocks)
       ExitDiagBlock();

 
 void SDiagsRenderer::emitCodeContext(FullSourceLoc Loc,
                                      DiagnosticsEngine::Level Level,
                                      SmallVectorImpl<CharSourceRange> &Ranges,
                                      ArrayRef<FixItHint> Hints) {
   Writer.EmitCodeContext(Ranges, Hints, Loc.getManager());
 }
 
+void SDiagsWriter::EmitDocumentation(ArrayRef<StringRef> URLs) {
+  llvm::BitstreamWriter &Stream = State->Stream;
+  RecordData &Record = State->Record;
+  AbbreviationMap &Abbrevs = State->Abbrevs;
+
+  for (ArrayRef<StringRef>::iterator I = URLs.begin(), E = URLs.end(); I != E;
+       ++I) {
+    unsigned ID = getEmitDocumentationURL(*I);
+    Record.clear();
+    Record.push_back(ID);
+    Stream.EmitRecord(RECORD_DOCUMENTATION, Record,
+                      Abbrevs.get(RECORD_DOCUMENTATION));
+  }
+}
+
 void SDiagsRenderer::emitNote(FullSourceLoc Loc, StringRef Message) {
   Writer.EnterDiagBlock();
   PresumedLoc PLoc = Loc.hasManager() ? Loc.getPresumedLoc() : PresumedLoc();
   Writer.EmitDiagnosticMessage(Loc, PLoc, DiagnosticsEngine::Note, Message,
                                DiagOrStoredDiag());
   Writer.ExitDiagBlock();
 }
 
std::error_code SDiagsMerger::visitCategoryRecord(unsigned ID, StringRef Name) {
   CategoryLookup[ID] = Writer.getEmitCategory(ID);
   return std::error_code();
 }
 
 std::error_code SDiagsMerger::visitDiagFlagRecord(unsigned ID, StringRef Name) {
   DiagFlagLookup[ID] = Writer.getEmitDiagnosticFlag(Name);
   return std::error_code();
 }
+
+std::error_code SDiagsMerger::visitDocumentationURLRecord(unsigned ID,
+                                                          StringRef URL) {
+  DocumentationLookup[ID] = Writer.getEmitDocumentationURL(URL);
+  return std::error_code();
+}
+
+std::error_code SDiagsMerger::visitDocumentationRecord(unsigned ID) {
+  RecordData::value_type Record[] = {DocumentationLookup[ID]};
+  Writer.State->Stream.EmitRecord(
+      RECORD_DOCUMENTATION, Record,
+      Writer.State->Abbrevs.get(RECORD_DOCUMENTATION));
+  return std::error_code();
+}

clang/lib/Frontend/SerializedDiagnosticReader.cpp

case RECORD_SOURCE_RANGE:
       continue;
     case RECORD_VERSION:
       // A version is just a number.
       if (Record.size() != 1)
         return SDError::MalformedDiagnosticRecord;
       if ((EC = visitVersionRecord(Record[0])))
         return EC;
       continue;
+    case RECORD_DOCUMENTATION_URL:
+      // A documentation URL has an ID and URL size.
+      if (Record.size() != 2)
+        return SDError::MalformedDiagnosticRecord;
+      if ((EC = visitDocumentationURLRecord(/*ID*/ Record[0], /*URL*/ Blob)))
+        return EC;
+      continue;
+    case RECORD_DOCUMENTATION:
+      // A documentation record just has an ID.
+      if (Record.size() != 1)
+        return SDError::MalformedDiagnosticRecord;
+      if ((EC = visitDocumentationRecord(/*ID*/ Record[0])))
+        return EC;
+      continue;
     }
   }
 }
 
 namespace {
 
 class SDErrorCategoryType final : public std::error_category {
   const char *name() const noexcept override {

clang/test/Misc/serialized-diags-documentation.c

+// RUN: c-index-test -read-diagnostics %S/Inputs/serialized-diags-documentation.dia 2>&1 | FileCheck %s
+
+// CHECK: hello.swift:1:1: error: non-nominal type '(Int, Int)' cannot be extended [] []
+// CHECK: [Documentation URL: {{.*}}/doc/swift/diagnostics/nominal-types.md]

clang/tools/c-index-test/c-index-test.c

 /******************************************************************************/
 
 typedef void (*PostVisitTU)(CXTranslationUnit);
 
 void PrintDiagnostic(CXDiagnostic Diagnostic) {
   FILE *out = stderr;
   CXFile file;
   CXString Msg;
+  CXStringSet *DocumentationURLs = NULL;
   unsigned display_opts = CXDiagnostic_DisplaySourceLocation
     | CXDiagnostic_DisplayColumn | CXDiagnostic_DisplaySourceRanges
     | CXDiagnostic_DisplayOption;
-  unsigned i, num_fixits;
+  unsigned i, count;
 
   if (clang_getDiagnosticSeverity(Diagnostic) == CXDiagnostic_Ignored)
     return;
 
   Msg = clang_formatDiagnostic(Diagnostic, display_opts);
   fprintf(stderr, "%s\n", clang_getCString(Msg));
   clang_disposeString(Msg);
 
   clang_getSpellingLocation(clang_getDiagnosticLocation(Diagnostic),
                             &file, 0, 0, 0);
   if (!file)
     return;
 
-  num_fixits = clang_getDiagnosticNumFixIts(Diagnostic);
-  fprintf(stderr, "Number FIX-ITs = %d\n", num_fixits);
-  for (i = 0; i != num_fixits; ++i) {
+  count = clang_getDiagnosticNumFixIts(Diagnostic);
+  fprintf(stderr, "Number FIX-ITs = %d\n", count);
+  for (i = 0; i != count; ++i) {
     CXSourceRange range;
     CXString insertion_text = clang_getDiagnosticFixIt(Diagnostic, i, &range);
     CXSourceLocation start = clang_getRangeStart(range);
     CXSourceLocation end = clang_getRangeEnd(range);
     unsigned start_line, start_column, end_line, end_column;
     CXFile start_file, end_file;
     clang_getSpellingLocation(start, &start_file, &start_line,
                               &start_column, 0);
if (clang_equalLocations(start, end)) {
       if (start_file == end_file) {
         fprintf(out, "FIX-IT: Replace ");
         PrintExtent(out, start_line, start_column, end_line, end_column);
         fprintf(out, " with \"%s\"\n", clang_getCString(insertion_text));
       }
     }
     clang_disposeString(insertion_text);
   }
+
+  DocumentationURLs = clang_getDiagnosticDocumentationURLs(Diagnostic);
+  if (DocumentationURLs) {
+    for (i = 0, count = DocumentationURLs->Count; i < count; ++i)
+      printf("[Documentation URL: %s]\n",
+             clang_getCString(DocumentationURLs->Strings[i]));
+    clang_disposeStringSet(DocumentationURLs);
+  }
 }
 
 void PrintDiagnosticSet(CXDiagnosticSet Set) {
   int i = 0, n = clang_getNumDiagnosticsInSet(Set);
   for ( ; i != n ; ++i) {
     CXDiagnostic Diag = clang_getDiagnosticInSet(Set, i);
     CXDiagnosticSet ChildDiags = clang_getChildDiagnostics(Diag);
     PrintDiagnostic(Diag);
for (i = 0 ; i < n; ++i) {
     printLocation(clang_getRangeStart(ReplacementRange));
     fprintf(stderr, " - ");
     printLocation(clang_getRangeEnd(ReplacementRange));
     fprintf(stderr, "): \"%s\"\n", clang_getCString(text));
     clang_disposeString(text);
   }  
 }
 
+static void printDocumentationURLs(CXDiagnostic D, unsigned indent) {
+  unsigned i, count;
+  CXStringSet *DocumentationURLs = clang_getDiagnosticDocumentationURLs(D);
+  for (i = 0, count = DocumentationURLs->Count; i < count; ++i) {
+    printIndent(indent);
+    printf("[Documentation URL: %s]\n",
+           clang_getCString(DocumentationURLs->Strings[i]));
+  }
+  clang_disposeStringSet(DocumentationURLs);
+}
+
 static void printDiagnosticSet(CXDiagnosticSet Diags, unsigned indent) {
   unsigned i, n;
 
   if (!Diags)
     return;
   
   n = clang_getNumDiagnosticsInSet(Diags);
   for (i = 0; i < n; ++i) {
for (i = 0; i < n; ++i) {
     if (DiagCatStr) {
       fprintf(stderr, " [%s]", DiagCatStr);
     }
     
     fprintf(stderr, "\n");
     
     printRanges(D, indent);
     printFixIts(D, indent);
-    
+    printDocumentationURLs(D, indent);
     /* Print subdiagnostics. */
     printDiagnosticSet(clang_getChildDiagnostics(D), indent+2);
 
     clang_disposeString(FileName);
     clang_disposeString(DiagSpelling);
     clang_disposeString(DiagOption);
     clang_disposeString(DiagCat);
   }  

clang/tools/libclang/CIndexDiagnostic.h

public:
 
   /// Return the number of FixIts.
   virtual unsigned getNumFixIts() const = 0;
 
   /// Return the FixIt information (source range and inserted text).
   virtual CXString getFixIt(unsigned FixIt,
                             CXSourceRange *ReplacementRange) const = 0;
 
+  /// Return the documentation URLs associated with the diagnostic.
+  virtual CXStringSet *getDocumentationURLs() const = 0;
+
   Kind getKind() const { return K; }
   
   CXDiagnosticSetImpl &getChildDiagnostics() {
     return ChildDiags;
   }
   
 protected:
   CXDiagnosticImpl(Kind k) : K(k) {}
struct CXStoredDiagnostic : public CXDiagnosticImpl {
 
   /// Return the number of FixIts.
   unsigned getNumFixIts() const override;
 
   /// Return the FixIt information (source range and inserted text).
   CXString getFixIt(unsigned FixIt,
                     CXSourceRange *ReplacementRange) const override;
 
+  /// Return the documentation URLs associated with the diagnostic.
+  CXStringSet *getDocumentationURLs() const override;
+
   static bool classof(const CXDiagnosticImpl *D) {
     return D->getKind() == StoredDiagnosticKind;
   }
 };
 
 namespace cxdiag {
 CXDiagnosticSetImpl *lazyCreateDiags(CXTranslationUnit TU,
                                      bool checkIfChanged = false);
 } // end namespace cxdiag
 
 } // end namespace clang
 
 #endif

clang/tools/libclang/CIndexDiagnostic.cpp

public:
   }
   unsigned getNumFixIts() const override { return 0; }
   CXString getFixIt(unsigned FixIt,
                     CXSourceRange *ReplacementRange) const override {
     if (ReplacementRange)
       *ReplacementRange = clang_getNullRange();
     return cxstring::createEmpty();
   }
+  CXStringSet *getDocumentationURLs() const override {
+    return cxstring::createSet({});
+  }
 };    
     
 class CXDiagnosticRenderer : public DiagnosticNoteRenderer {
 public:  
   CXDiagnosticRenderer(const LangOptions &LangOpts,
                        DiagnosticOptions *DiagOpts,
                        CXDiagnosticSetImpl *mainSet)
   : DiagnosticNoteRenderer(LangOpts, DiagOpts),
CXString clang_getDiagnosticFixIt(CXDiagnostic Diag, unsigned FixIt,
   if (!D || FixIt >= D->getNumFixIts()) {
     if (ReplacementRange)
       *ReplacementRange = clang_getNullRange();
     return cxstring::createEmpty();
   }
   return D->getFixIt(FixIt, ReplacementRange);
 }
 
+CXStringSet *clang_getDiagnosticDocumentationURLs(CXDiagnostic Diagnostic) {
+  if (CXDiagnosticImpl *D = static_cast<CXDiagnosticImpl *>(Diagnostic))
+    return D->getDocumentationURLs();
+  return cxstring::createSet({});
+}
+
 void clang_disposeDiagnosticSet(CXDiagnosticSet Diags) {
   if (CXDiagnosticSetImpl *D = static_cast<CXDiagnosticSetImpl *>(Diags)) {
     if (D->isExternallyManaged())
       delete D;
   }
 }
   
 CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags,

clang/tools/libclang/CXLoadedDiagnostic.h

public:
 
   /// Return the number of FixIts.
   unsigned getNumFixIts() const override;
 
   /// Return the FixIt information (source range and inserted text).
   CXString getFixIt(unsigned FixIt,
                     CXSourceRange *ReplacementRange) const override;
 
+  /// Return the documentation URLs associated with the diagnostic.
+  virtual CXStringSet *getDocumentationURLs() const override;
+
   static bool classof(const CXDiagnosticImpl *D) {
     return D->getKind() == LoadedDiagnosticKind;
   }
   
   /// Decode the CXSourceLocation into file, line, column, and offset.
   static void decodeLocation(CXSourceLocation location,
                              CXFile *file,
                              unsigned *line,
                              unsigned *column,
                              unsigned *offset);
 
   struct Location {
     CXFile file;
     unsigned line;
     unsigned column;
     unsigned offset;
     
     Location() : line(0), column(0), offset(0) {}    
   };
   
   Location DiagLoc;
 
   std::vector<CXSourceRange> Ranges;
   std::vector<std::pair<CXSourceRange, const char *> > FixIts;
+  std::vector<std::string> DocumentationURLs;
   const char *Spelling;
   llvm::StringRef DiagOption;
   llvm::StringRef CategoryText;
   unsigned severity;
   unsigned category;
 };
 }
 
 #endif

clang/tools/libclang/CXLoadedDiagnostic.cpp

 public:
   CXLoadedDiagnosticSetImpl() : CXDiagnosticSetImpl(true), FakeFiles(FO) {}
   ~CXLoadedDiagnosticSetImpl() override {}
 
   llvm::BumpPtrAllocator Alloc;
   Strings Categories;
   Strings WarningFlags;
   Strings FileNames;
-  
+  Strings DocumentationURLs;
   FileSystemOptions FO;
   FileManager FakeFiles;
   llvm::DenseMap<unsigned, const FileEntry *> Files;
 
   /// Copy the string into our own allocator.
   const char *copyString(StringRef Blob) {
     char *mem = Alloc.Allocate<char>(Blob.size() + 1);
     memcpy(mem, Blob.data(), Blob.size());

 CXString CXLoadedDiagnostic::getFixIt(unsigned FixIt,
                                       CXSourceRange *ReplacementRange) const {
   assert(FixIt < FixIts.size());
   if (ReplacementRange)
     *ReplacementRange = FixIts[FixIt].first;
   return cxstring::createRef(FixIts[FixIt].second);
 }
 
+CXStringSet *CXLoadedDiagnostic::getDocumentationURLs() const {
+  return cxstring::createSet(DocumentationURLs);
+}
+
 void CXLoadedDiagnostic::decodeLocation(CXSourceLocation location,
                                         CXFile *file,
                                         unsigned int *line,
                                         unsigned int *column,
                                         unsigned int *offset) {
   
   
   // CXSourceLocation consists of the following fields:
protected:
   std::error_code visitFixitRecord(const serialized_diags::Location &Start,
                                    const serialized_diags::Location &End,
                                    StringRef CodeToInsert) override;
 
   std::error_code
   visitSourceRangeRecord(const serialized_diags::Location &Start,
                          const serialized_diags::Location &End) override;
 
+  std::error_code visitDocumentationURLRecord(unsigned ID,
+                                              StringRef Path) override;
+  std::error_code visitDocumentationRecord(unsigned ID) override;
+
 public:
   DiagLoader(enum CXLoadDiag_Error *e, CXString *es)
       : SerializedDiagnosticReader(), error(e), errorString(es) {
     if (error)
       *error = CXLoadDiag_None;
     if (errorString)
       *errorString = cxstring::createEmpty();
   }
std::error_code DiagLoader::visitFilenameRecord(unsigned ID, unsigned Size,
   if (Name.size() > 65536)
     return reportInvalidFile("Out-of-bounds string in filename");
   TopDiags->FileNames[ID] = TopDiags->copyString(Name);
   TopDiags->Files[ID] =
       TopDiags->FakeFiles.getVirtualFile(Name, Size, Timestamp);
   return std::error_code();
 }
 
+std::error_code DiagLoader::visitDocumentationURLRecord(unsigned ID,
+                                                        StringRef Path) {
+  // FIXME: Why do we care about long strings?
+  if (Path.size() > 65536)
+    return reportInvalidFile("Out-of-bounds string in documentation URL.");
+  TopDiags->DocumentationURLs[ID] = TopDiags->copyString(Path);
+  return std::error_code();
+}
+
 std::error_code
 DiagLoader::visitSourceRangeRecord(const serialized_diags::Location &Start,
                                    const serialized_diags::Location &End) {
   CXSourceRange SR;
   if (std::error_code EC = readRange(Start, End, SR))
     return EC;
   CurrentDiags.back()->Ranges.push_back(SR);
   return std::error_code();
DiagLoader::visitFixitRecord(const serialized_diags::Location &Start,
   // FIXME: Why do we care about long strings?
   if (CodeToInsert.size() > 65536)
     return reportInvalidFile("Out-of-bounds string in FIXIT");
   CurrentDiags.back()->FixIts.push_back(
       std::make_pair(SR, TopDiags->copyString(CodeToInsert)));
   return std::error_code();
 }
 
+std::error_code DiagLoader::visitDocumentationRecord(unsigned ID) {
+  CurrentDiags.back()->DocumentationURLs.push_back(
+      TopDiags->DocumentationURLs[ID]);
+  return std::error_code();
+}
+
 std::error_code DiagLoader::visitDiagnosticRecord(
     unsigned Severity, const serialized_diags::Location &Location,
     unsigned Category, unsigned Flag, StringRef Message) {
   CXLoadedDiagnostic &D = *CurrentDiags.back();
   D.severity = Severity;
   if (std::error_code EC = readLocation(Location, D.DiagLoc))
     return EC;
   D.category = Category;

clang/tools/libclang/CXStoredDiagnostic.cpp

if (ReplacementRange) {
     // removal) range, adjusting the end of the range to point to
     // the end of the token.
     *ReplacementRange = translateSourceRange(Diag.getLocation().getManager(),
                                              LangOpts, Hint.RemoveRange);
   }
   return cxstring::createDup(Hint.CodeToInsert);
 }
 
+CXStringSet *CXStoredDiagnostic::getDocumentationURLs() const {
+  // Documentation URLs are not yet implemented for native Clang diagnostics.
+  return cxstring::createSet({});
+}

clang/tools/libclang/libclang.exports

 clang_getCursorUSR
 clang_getCursorVisibility
 clang_getDeclObjCTypeEncoding
 clang_getDefinitionSpellingAndExtent
 clang_getDiagnostic
 clang_getDiagnosticCategory
 clang_getDiagnosticCategoryName
 clang_getDiagnosticCategoryText
+clang_getDiagnosticDocumentationURLs
 clang_getDiagnosticFixIt
 clang_getDiagnosticInSet
 clang_getDiagnosticLocation
 clang_getDiagnosticNumFixIts
 clang_getDiagnosticNumRanges
 clang_getDiagnosticOption
 clang_getDiagnosticRange
 clang_getDiagnosticSetFromTU