[clang-doc] Add link to source code in file definitions

[DiegoAstiazaran]

Summary

Two command line options have been added to clang-doc.

--repository=<string>       - URL of repository that hosts code; used for links to definition locations.
--source-root=<string>      - Directory where processed files are stored. Links to definition locations will only be generated if the file is in this dir.

If the file is in the root-directory and a repository options is passed; a link to the source code will be rendered by the HTML generator.

[Eugene.Zelenko]

It'll be reasonable to mention new command-line arguments in documentation and Release Notes.

[jakehehrlich]

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

376

Add a comment here that this is the github/googlesource notation for this that way in the future people arren't confused when it doesn't work for other hosting pages

377–378

Can you put these in the link so that the link is larger than a single number? e.g. "303 of file foo.c" should be linkified rather than just "303" which is how I read the code now.

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

103–104

Do you actually need to do this? Feels like a bug in replace_path_prefix per its own documentation if you do.

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp

228

1. Do we need to add this for the user?
2. Can we use https by default if we need this?

[DiegoAstiazaran]

Change http to https as the default fix to the repository link.
Add new flags to clang-doc documentation.

[DiegoAstiazaran]

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

377–378

"303" is linkified to the specific line in the source code but also "foo.c" is linkified to the top of the source code page.
This is how it is done in Doxygen documentation.
I think it would look weird to have " of file " linkified. But talking to @phosek, we agreed that it would be better to remove the whole "Defined at ..." and make the info name linkified to the definition, with a tooltip that shows "foo.c:303".
So I think we could leave it like this for now and later, in another patch (this will require some CSS), do what I just mentioned. What do you think?

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

103–104

replace_path_prefix simply calls substr() on the path so if the prefix does not include the separator at the end, the resulting path will have it at the beginning.

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp

228

Not required but I consider it'd be nice to have it.
You're right, https should be the default.

[juliehockett]

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

377–378

While the tooltip idea seems interesting, I'm inclined to keep the "Defined at" portion and an actual link with the text for now. I'd want to see an example of what the tooltip option would look like before going with it.

For now, the separate line number and file linkification SGTM.

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

40

Don't use auto here, since it's not immediately obvious what the type is.

103–104

Leave a comment to that effect, then.

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp

71

Can we call this --source-root?

228

This is fine, but please add a test case for the when the user omits the prefix.

clang-tools-extra/docs/clang-doc.rst

93 ↗

(On Diff #213169)

Formatting here is a bit weird

[DiegoAstiazaran]

Add comments.
Change name of flag; root-directory -> --source-root
Moved fixing of repository link to ClangDocContext constructor and add test where the prefix is omitted.
RepositoryLink in ClangDocContext struct and writeFileDefinition function is now llvm::Optional<>

clang-tools-extra/docs/clang-doc.rst

93 ↗

(On Diff #213169)

Do you mean the almost empty line that's only "-"? This is because the description of the flag starts with \n.

R"(
URL of repository that hosts code.
Used for links to definition locations.)"

I used the same format used by clang-tidy, it has this format for all the multi-line flag descriptions.

[DiegoAstiazaran]

Remove unnecessary type casting.

[juliehockett]

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

354

Move to .cpp file (now that it has a non-trivial implementation)

357

Comment

[DiegoAstiazaran]

Add comments.
Move definition of ClangDocContext constructor to .cpp file.

[DiegoAstiazaran]

Rebase to master

[juliehockett]

LGTM

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

llvm::Error decodeRecord(Record R, TagTypeKind &Field, llvm::StringRef Blob) {
   }
 }
 
 llvm::Error decodeRecord(Record R, llvm::Optional<Location> &Field,
                          llvm::StringRef Blob) {
   if (R[0] > INT_MAX)
     return llvm::make_error<llvm::StringError>("Integer too large to parse.\n",
                                                llvm::inconvertibleErrorCode());
-  Field.emplace((int)R[0], Blob);
+  Field.emplace((int)R[0], Blob, (bool)R[1]);
   return llvm::Error::success();
 }
 
 llvm::Error decodeRecord(Record R, InfoType &Field, llvm::StringRef Blob) {
   switch (auto IT = static_cast<InfoType>(R[0])) {
   case InfoType::IT_namespace:
   case InfoType::IT_record:
   case InfoType::IT_function:
llvm::Error decodeRecord(Record R,
   return llvm::Error::success();
 }
 
 llvm::Error decodeRecord(Record R, llvm::SmallVectorImpl<Location> &Field,
                          llvm::StringRef Blob) {
   if (R[0] > INT_MAX)
     return llvm::make_error<llvm::StringError>("Integer too large to parse.\n",
                                                llvm::inconvertibleErrorCode());
-  Field.emplace_back((int)R[0], Blob);
+  Field.emplace_back((int)R[0], Blob, (bool)R[1]);
   return llvm::Error::success();
 }
 
 llvm::Error parseRecord(Record R, unsigned ID, llvm::StringRef Blob,
                         const unsigned VersionNo) {
   if (ID == VERSION && R[0] == VersionNo)
     return llvm::Error::success();
   return llvm::make_error<llvm::StringError>(

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

 
 // Assumes that the file will not have more than 65535 lines.
 static void LocationAbbrev(std::shared_ptr<llvm::BitCodeAbbrev> &Abbrev) {
   AbbrevGen(
       Abbrev,
       {// 0. Fixed-size integer (line number)
        llvm::BitCodeAbbrevOp(llvm::BitCodeAbbrevOp::Fixed,
                              BitCodeConstants::LineNumberSize),
-       // 1. Fixed-size integer (length of the following string (filename))
+       // 1. Boolean (IsFileInRootDir)
+       llvm::BitCodeAbbrevOp(llvm::BitCodeAbbrevOp::Fixed,
+                             BitCodeConstants::BoolSize),
+       // 2. Fixed-size integer (length of the following string (filename))
        llvm::BitCodeAbbrevOp(llvm::BitCodeAbbrevOp::Fixed,
                              BitCodeConstants::StringLengthSize),
-       // 2. The string blob
+       // 3. The string blob
        llvm::BitCodeAbbrevOp(llvm::BitCodeAbbrevOp::Blob)});
 }
 
 struct RecordIdDsc {
   llvm::StringRef Name;
   AbbrevDsc Abbrev = nullptr;
 
   RecordIdDsc() = default;
void ClangDocBitcodeWriter::emitRecord(const Location &Loc, RecordId ID) {
   assert(RecordIdNameMap[ID] && "Unknown RecordId.");
   assert(RecordIdNameMap[ID].Abbrev == &LocationAbbrev &&
          "Abbrev type mismatch.");
   if (!prepRecordData(ID, true))
     return;
   // FIXME: Assert that the line number is of the appropriate size.
   Record.push_back(Loc.LineNumber);
   assert(Loc.Filename.size() < (1U << BitCodeConstants::StringLengthSize));
+  Record.push_back(Loc.IsFileInRootDir);
   Record.push_back(Loc.Filename.size());
   Stream.EmitRecordWithBlob(Abbrevs.get(ID), Record, Loc.Filename);
 }
 
 void ClangDocBitcodeWriter::emitRecord(bool Val, RecordId ID) {
   assert(RecordIdNameMap[ID] && "Unknown RecordId.");
   assert(RecordIdNameMap[ID].Abbrev == &BoolAbbrev && "Abbrev type mismatch.");
   if (!prepRecordData(ID, Val))

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

genReferenceList(const llvm::SmallVectorImpl<Reference> &Refs,
   for (const auto &R : Refs) {
     if (&R != Refs.begin())
       Out.emplace_back(llvm::make_unique<TextNode>(", "));
     Out.emplace_back(genTypeReference(R, CurrentDirectory));
   }
   return Out;
 }
 
-static std::vector<std::unique_ptr<TagNode>> genHTML(const EnumInfo &I);
-static std::vector<std::unique_ptr<TagNode>> genHTML(const FunctionInfo &I,
-                                                     StringRef ParentInfoDir);
+static std::vector<std::unique_ptr<TagNode>>
+genHTML(const EnumInfo &I, const ClangDocContext &CDCtx);
+static std::vector<std::unique_ptr<TagNode>>
+genHTML(const FunctionInfo &I, const ClangDocContext &CDCtx,
 
 static std::vector<std::unique_ptr<TagNode>>
-genEnumsBlock(const std::vector<EnumInfo> &Enums) {
+genEnumsBlock(const std::vector<EnumInfo> &Enums,
+              const ClangDocContext &CDCtx) {
   if (Enums.empty())
     return {};
 
   std::vector<std::unique_ptr<TagNode>> Out;
   Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_H2, "Enums"));
   Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_DIV));
   auto &DivBody = Out.back();
   for (const auto &E : Enums) {
-    std::vector<std::unique_ptr<TagNode>> Nodes = genHTML(E);
+    std::vector<std::unique_ptr<TagNode>> Nodes = genHTML(E, CDCtx);
     AppendVector(std::move(Nodes), DivBody->Children);
   }
   return Out;
 }
 
 static std::unique_ptr<TagNode>
 genEnumMembersBlock(const llvm::SmallVector<SmallString<16>, 4> &Members) {
   if (Members.empty())
     return nullptr;
 
   auto List = llvm::make_unique<TagNode>(HTMLTag::TAG_UL);
   for (const auto &M : Members)
     List->Children.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_LI, M));
   return List;
 }
 
 static std::vector<std::unique_ptr<TagNode>>
 genFunctionsBlock(const std::vector<FunctionInfo> &Functions,
-                  StringRef ParentInfoDir) {
+                  const ClangDocContext &CDCtx, StringRef ParentInfoDir) {
   if (Functions.empty())
     return {};
 
   std::vector<std::unique_ptr<TagNode>> Out;
   Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_H2, "Functions"));
   Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_DIV));
   auto &DivBody = Out.back();
   for (const auto &F : Functions) {
-    std::vector<std::unique_ptr<TagNode>> Nodes = genHTML(F, ParentInfoDir);
+    std::vector<std::unique_ptr<TagNode>> Nodes =
+        genHTML(F, CDCtx, ParentInfoDir);
     AppendVector(std::move(Nodes), DivBody->Children);
   }
   return Out;
 }
 
 static std::vector<std::unique_ptr<TagNode>>
 genRecordMembersBlock(const llvm::SmallVector<MemberTypeInfo, 4> &Members,
                       StringRef ParentInfoDir) {
genReferencesBlock(const std::vector<Reference> &References,
   Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_UL));
   auto &ULBody = Out.back();
   for (const auto &R : References)
     ULBody->Children.emplace_back(
         llvm::make_unique<TagNode>(HTMLTag::TAG_LI, R.Name));
   return Out;
 }
 
-static std::unique_ptr<TagNode> writeFileDefinition(const Location &L) {
+static std::unique_ptr<TagNode> writeFileDefinition(const Location &L,
+                                                    StringRef RepositoryUrl) {
+  if (!L.IsFileInRootDir || RepositoryUrl.empty())
     return llvm::make_unique<TagNode>(
-      HTMLTag::TAG_P,
-      "Defined at line " + std::to_string(L.LineNumber) + " of " + L.Filename);
+        HTMLTag::TAG_P, "Defined at line " + std::to_string(L.LineNumber) +
+                            " of file " + L.Filename);
+  SmallString<128> FileURL(RepositoryUrl);
+  llvm::sys::path::append(FileURL, llvm::sys::path::Style::posix, L.Filename);
+  auto Node = llvm::make_unique<TagNode>(HTMLTag::TAG_P);
+  Node->Children.emplace_back(llvm::make_unique<TextNode>("Defined at line "));
+  auto LocNumberNode =
+      llvm::make_unique<TagNode>(HTMLTag::TAG_A, std::to_string(L.LineNumber));
+  LocNumberNode->Attributes.try_emplace(
+      "href", (FileURL + "#" + std::to_string(L.LineNumber)).str());
+  Node->Children.emplace_back(std::move(LocNumberNode));
+  Node->Children.emplace_back(llvm::make_unique<TextNode>(" of file "));
+  auto LocFileNode = llvm::make_unique<TagNode>(
+      HTMLTag::TAG_A, llvm::sys::path::filename(FileURL));
+  LocFileNode->Attributes.try_emplace("href", FileURL);
+  Node->Children.emplace_back(std::move(LocFileNode));
+  return Node;
 }
 
 static std::unique_ptr<HTMLNode> genHTML(const CommentInfo &I) {
   if (I.Kind == "FullComment") {
     auto FullComment = llvm::make_unique<TagNode>(HTMLTag::TAG_DIV);
     for (const auto &Child : I.Children) {
       std::unique_ptr<HTMLNode> Node = genHTML(*Child);
       if (Node)
static std::unique_ptr<TagNode> genHTML(const std::vector<CommentInfo> &C) {
   auto CommentBlock = llvm::make_unique<TagNode>(HTMLTag::TAG_DIV);
   for (const auto &Child : C) {
     if (std::unique_ptr<HTMLNode> Node = genHTML(Child))
       CommentBlock->Children.emplace_back(std::move(Node));
   }
   return CommentBlock;
 }
 
-static std::vector<std::unique_ptr<TagNode>> genHTML(const EnumInfo &I) {
+static std::vector<std::unique_ptr<TagNode>>
+genHTML(const EnumInfo &I, const ClangDocContext &CDCtx) {
   std::vector<std::unique_ptr<TagNode>> Out;
   std::string EnumType;
   if (I.Scoped)
     EnumType = "enum class ";
   else
     EnumType = "enum ";
 
   Out.emplace_back(
       llvm::make_unique<TagNode>(HTMLTag::TAG_H3, EnumType + I.Name));
 
   std::unique_ptr<TagNode> Node = genEnumMembersBlock(I.Members);
   if (Node)
     Out.emplace_back(std::move(Node));
 
   if (I.DefLoc)
-    Out.emplace_back(writeFileDefinition(I.DefLoc.getValue()));
+    Out.emplace_back(
+        writeFileDefinition(I.DefLoc.getValue(), CDCtx.RepositoryUrl));
 
   std::string Description;
   if (!I.Description.empty())
     Out.emplace_back(genHTML(I.Description));
 
   return Out;
 }
 
-static std::vector<std::unique_ptr<TagNode>> genHTML(const FunctionInfo &I,
-                                                     StringRef ParentInfoDir) {
+static std::vector<std::unique_ptr<TagNode>>
+genHTML(const FunctionInfo &I, const ClangDocContext &CDCtx,
   std::vector<std::unique_ptr<TagNode>> Out;
   Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_H3, I.Name));
 
   Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_P));
   auto &FunctionHeader = Out.back();
 
   std::string Access = getAccess(I.Access);
   if (Access != "")
for (const auto &P : I.Params) {
     FunctionHeader->Children.emplace_back(
         genTypeReference(P.Type, ParentInfoDir));
     FunctionHeader->Children.emplace_back(
         llvm::make_unique<TextNode>(" " + P.Name));
   }
   FunctionHeader->Children.emplace_back(llvm::make_unique<TextNode>(")"));
 
   if (I.DefLoc)
-    Out.emplace_back(writeFileDefinition(I.DefLoc.getValue()));
+    Out.emplace_back(
+        writeFileDefinition(I.DefLoc.getValue(), CDCtx.RepositoryUrl));
 
   std::string Description;
   if (!I.Description.empty())
     Out.emplace_back(genHTML(I.Description));
 
   return Out;
 }
 
-static std::vector<std::unique_ptr<TagNode>> genHTML(const NamespaceInfo &I,
-                                                     std::string &InfoTitle) {
+static std::vector<std::unique_ptr<TagNode>>
+genHTML(const NamespaceInfo &I, const ClangDocContext &CDCtx,
   std::vector<std::unique_ptr<TagNode>> Out;
   if (I.Name.str() == "")
     InfoTitle = "Global Namespace";
   else
     InfoTitle = ("namespace " + I.Name).str();
 
   Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_H1, InfoTitle));
 
   std::string Description;
   if (!I.Description.empty())
     Out.emplace_back(genHTML(I.Description));
 
   std::vector<std::unique_ptr<TagNode>> ChildNamespaces =
       genReferencesBlock(I.ChildNamespaces, "Namespaces");
   AppendVector(std::move(ChildNamespaces), Out);
   std::vector<std::unique_ptr<TagNode>> ChildRecords =
       genReferencesBlock(I.ChildRecords, "Records");
   AppendVector(std::move(ChildRecords), Out);
 
   std::vector<std::unique_ptr<TagNode>> ChildFunctions =
-      genFunctionsBlock(I.ChildFunctions, I.Path);
+      genFunctionsBlock(I.ChildFunctions, CDCtx, I.Path);
   AppendVector(std::move(ChildFunctions), Out);
   std::vector<std::unique_ptr<TagNode>> ChildEnums =
-      genEnumsBlock(I.ChildEnums);
+      genEnumsBlock(I.ChildEnums, CDCtx);
   AppendVector(std::move(ChildEnums), Out);
 
   return Out;
 }
 
-static std::vector<std::unique_ptr<TagNode>> genHTML(const RecordInfo &I,
-                                                     std::string &InfoTitle) {
+static std::vector<std::unique_ptr<TagNode>>
+genHTML(const RecordInfo &I, const ClangDocContext &CDCtx,
   std::vector<std::unique_ptr<TagNode>> Out;
   InfoTitle = (getTagType(I.TagType) + " " + I.Name).str();
   Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_H1, InfoTitle));
 
   if (I.DefLoc)
-    Out.emplace_back(writeFileDefinition(I.DefLoc.getValue()));
+    Out.emplace_back(
+        writeFileDefinition(I.DefLoc.getValue(), CDCtx.RepositoryUrl));
 
   std::string Description;
   if (!I.Description.empty())
     Out.emplace_back(genHTML(I.Description));
 
   std::vector<std::unique_ptr<HTMLNode>> Parents =
       genReferenceList(I.Parents, I.Path);
   std::vector<std::unique_ptr<HTMLNode>> VParents =
genHTML(const RecordInfo &I, const ClangDocContext &CDCtx,
   std::vector<std::unique_ptr<TagNode>> Members =
       genRecordMembersBlock(I.Members, I.Path);
   AppendVector(std::move(Members), Out);
   std::vector<std::unique_ptr<TagNode>> ChildRecords =
       genReferencesBlock(I.ChildRecords, "Records");
   AppendVector(std::move(ChildRecords), Out);
 
   std::vector<std::unique_ptr<TagNode>> ChildFunctions =
-      genFunctionsBlock(I.ChildFunctions, I.Path);
+      genFunctionsBlock(I.ChildFunctions, CDCtx, I.Path);
   AppendVector(std::move(ChildFunctions), Out);
   std::vector<std::unique_ptr<TagNode>> ChildEnums =
-      genEnumsBlock(I.ChildEnums);
+      genEnumsBlock(I.ChildEnums, CDCtx);
   AppendVector(std::move(ChildEnums), Out);
 
   return Out;
 }
 
 /// Generator for HTML documentation.
 class HTMLGenerator : public Generator {
 public:
llvm::Error HTMLGenerator::generateDocForInfo(Info *I, llvm::raw_ostream &OS,
   F.Children.emplace_back(std::move(MetaNode));
 
   std::string InfoTitle;
   Info CastedInfo;
   auto MainContentNode = llvm::make_unique<TagNode>(HTMLTag::TAG_DIV);
   switch (I->IT) {
   case InfoType::IT_namespace: {
     std::vector<std::unique_ptr<TagNode>> Nodes =
-        genHTML(*static_cast<clang::doc::NamespaceInfo *>(I), InfoTitle);
+        genHTML(*static_cast<clang::doc::NamespaceInfo *>(I), CDCtx, InfoTitle);
     AppendVector(std::move(Nodes), MainContentNode->Children);
     break;
   }
   case InfoType::IT_record: {
     std::vector<std::unique_ptr<TagNode>> Nodes =
-        genHTML(*static_cast<clang::doc::RecordInfo *>(I), InfoTitle);
+        genHTML(*static_cast<clang::doc::RecordInfo *>(I), CDCtx, InfoTitle);
     AppendVector(std::move(Nodes), MainContentNode->Children);
     break;
   }
   case InfoType::IT_enum: {
     std::vector<std::unique_ptr<TagNode>> Nodes =
-        genHTML(*static_cast<clang::doc::EnumInfo *>(I));
+        genHTML(*static_cast<clang::doc::EnumInfo *>(I), CDCtx);
     AppendVector(std::move(Nodes), MainContentNode->Children);
     break;
   }
   case InfoType::IT_function: {
     std::vector<std::unique_ptr<TagNode>> Nodes =
-        genHTML(*static_cast<clang::doc::FunctionInfo *>(I), "");
+        genHTML(*static_cast<clang::doc::FunctionInfo *>(I), CDCtx, "");
     AppendVector(std::move(Nodes), MainContentNode->Children);
     break;
   }
   case InfoType::IT_default:
     return llvm::make_error<llvm::StringError>("Unexpected info type.\n",
                                                llvm::inconvertibleErrorCode());
   }
 

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

public:
   bool VisitEnumDecl(const EnumDecl *D);
   bool VisitCXXMethodDecl(const CXXMethodDecl *D);
   bool VisitFunctionDecl(const FunctionDecl *D);
 
 private:
   template <typename T> bool mapDecl(const T *D);
 
   int getLine(const NamedDecl *D, const ASTContext &Context) const;
-  StringRef getFile(const NamedDecl *D, const ASTContext &Context) const;
+  llvm::SmallString<128> getFile(const NamedDecl *D, const ASTContext &Context,
+                                 StringRef RootDir,
+                                 bool &IsFileInRootDir) const;
   comments::FullComment *getComment(const NamedDecl *D,
                                     const ASTContext &Context) const;
 
   ClangDocContext CDCtx;
 };
 
 } // namespace doc
 } // namespace clang
 
 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_MAPPER_H

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

template <typename T> bool MapASTVisitor::mapDecl(const T *D) {
   // Skip function-internal decls.
   if (D->getParentFunctionOrMethod())
     return true;
 
   llvm::SmallString<128> USR;
   // If there is an error generating a USR for the decl, skip this decl.
   if (index::generateUSRForDecl(D, USR))
     return true;
-
-  auto I = serialize::emitInfo(
-      D, getComment(D, D->getASTContext()), getLine(D, D->getASTContext()),
-      getFile(D, D->getASTContext()), CDCtx.PublicOnly);
+  bool IsFileInRootDir;
+  auto File = getFile(D, D->getASTContext(), CDCtx.RootDir, IsFileInRootDir);
+  auto I = serialize::emitInfo(D, getComment(D, D->getASTContext()),
+                               getLine(D, D->getASTContext()), File,
+                               IsFileInRootDir, CDCtx.PublicOnly);
 
   // A null in place of I indicates that the serializer is skipping this decl
   // for some reason (e.g. we're only reporting public decls).
   if (I.first)
     CDCtx.ECtx->reportResult(llvm::toHex(llvm::toStringRef(I.first->USR)),
                              serialize::serialize(I.first));
   if (I.second)
     CDCtx.ECtx->reportResult(llvm::toHex(llvm::toStringRef(I.second->USR)),
MapASTVisitor::getComment(const NamedDecl *D, const ASTContext &Context) const {
   return nullptr;
 }
 
 int MapASTVisitor::getLine(const NamedDecl *D,
                            const ASTContext &Context) const {
   return Context.getSourceManager().getPresumedLoc(D->getBeginLoc()).getLine();
 }
 
-llvm::StringRef MapASTVisitor::getFile(const NamedDecl *D,
-                                       const ASTContext &Context) const {
-  return Context.getSourceManager()
+llvm::SmallString<128> MapASTVisitor::getFile(const NamedDecl *D,
+                                              const ASTContext &Context,
+                                              llvm::StringRef RootDir,
+                                              bool &IsFileInRootDir) const {
+  llvm::SmallString<128> File(Context.getSourceManager()
                                   .getPresumedLoc(D->getBeginLoc())
-      .getFilename();
+                                  .getFilename());
+  IsFileInRootDir = false;
+  if (RootDir.empty() || !File.startswith(RootDir))
+    return File;
+  IsFileInRootDir = true;
+  llvm::SmallString<128> Prefix(RootDir);
+  if (!llvm::sys::path::is_separator(Prefix.back()))
+    Prefix += llvm::sys::path::get_separator();
+  llvm::sys::path::replace_path_prefix(File, Prefix, "");
+  return File;
 }
 
 } // namespace doc
 } // namespace clang

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

AccessSpecifier Access = AccessSpecifier::AS_none; // Access level associated
                                                      // protected, private,
                                                      // none).
 };
 
 struct Location {
   Location() = default;
   Location(int LineNumber, SmallString<16> Filename)
       : LineNumber(LineNumber), Filename(std::move(Filename)) {}
+  Location(int LineNumber, SmallString<16> Filename, bool IsFileInRootDir)
+      : LineNumber(LineNumber), Filename(std::move(Filename)),
+        IsFileInRootDir(IsFileInRootDir) {}
 
   bool operator==(const Location &Other) const {
     return std::tie(LineNumber, Filename) ==
            std::tie(Other.LineNumber, Other.Filename);
   }
 
   // This operator is used to sort a vector of Locations.
   // No specific order (attributes more important than others) is required. Any
   // sort is enough, the order is only needed to call std::unique after sorting
   // the vector.
   bool operator<(const Location &Other) const {
     return std::tie(LineNumber, Filename) <
            std::tie(Other.LineNumber, Other.Filename);
   }
 
-  int LineNumber;           // Line number of this Location.
-  SmallString<32> Filename; // File for this Location.
+  int LineNumber;               // Line number of this Location.
+  SmallString<32> Filename;     // File for this Location.
+  bool IsFileInRootDir = false; // Indicates if file is inside root directory
 };
 
 /// A base struct for Infos.
 struct Info {
   Info() = default;
   Info(InfoType IT) : IT(IT) {}
   Info(InfoType IT, SymbolID USR) : USR(USR), IT(IT) {}
   Info(InfoType IT, SymbolID USR, StringRef Name)

 
 // A standalone function to call to merge a vector of infos into one.
 // This assumes that all infos in the vector are of the same type, and will fail
 // if they are different.
 llvm::Expected<std::unique_ptr<Info>>
 mergeInfos(std::vector<std::unique_ptr<Info>> &Values);
 
 struct ClangDocContext {
   tooling::ExecutionContext *ECtx;
   bool PublicOnly;
   std::string OutDirectory;
   std::vector<std::string> UserStylesheets;
+  std::string RootDir;
+  std::string RepositoryUrl;
 };
 
 } // namespace doc
 } // namespace clang
 
 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_REPRESENTATION_H

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

 // declaration's parent, it can be a NamespaceInfo or RecordInfo.
 // Both elements can be nullptrs if the declaration shouldn't be handled.
 // When the declaration is handled, the first element will be a nullptr for
 // EnumDecl, FunctionDecl and CXXMethodDecl; they are only returned wrapped in
 // its parent scope. For NamespaceDecl and RecordDecl both elements are not
 // nullptr.
 std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
 emitInfo(const NamespaceDecl *D, const FullComment *FC, int LineNumber,
-         StringRef File, bool PublicOnly);
+         StringRef File, bool IsFileInRootDir, bool PublicOnly);
 std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
 emitInfo(const RecordDecl *D, const FullComment *FC, int LineNumber,
-         StringRef File, bool PublicOnly);
+         StringRef File, bool IsFileInRootDir, bool PublicOnly);
 std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
 emitInfo(const EnumDecl *D, const FullComment *FC, int LineNumber,
-         StringRef File, bool PublicOnly);
+         StringRef File, bool IsFileInRootDir, bool PublicOnly);
 std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
 emitInfo(const FunctionDecl *D, const FullComment *FC, int LineNumber,
-         StringRef File, bool PublicOnly);
+         StringRef File, bool IsFileInRootDir, bool PublicOnly);
 std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
 emitInfo(const CXXMethodDecl *D, const FullComment *FC, int LineNumber,
-         StringRef File, bool PublicOnly);
+         StringRef File, bool IsFileInRootDir, bool PublicOnly);
 
 // Function to hash a given USR value for storage.
 // As USRs (Unified Symbol Resolution) could be large, especially for functions
 // with long type arguments, we use 160-bits SHA1(USR) values to
 // guarantee the uniqueness of symbols while using a relatively small amount of
 // memory (vs storing USRs directly).
 SymbolID hashUSR(llvm::StringRef USR);
 
 std::string serialize(std::unique_ptr<Info> &I);
 
 } // namespace serialize
 } // namespace doc
 } // namespace clang
 
 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_SERIALIZE_H

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

if (C) {
     I.Description.emplace_back();
     parseFullComment(C, I.Description.back());
   }
 }
 
 template <typename T>
 static void populateSymbolInfo(SymbolInfo &I, const T *D, const FullComment *C,
                                int LineNumber, StringRef Filename,
+                               bool IsFileInRootDir,
                                bool &IsInAnonymousNamespace) {
   populateInfo(I, D, C, IsInAnonymousNamespace);
   if (D->isThisDeclarationADefinition())
-    I.DefLoc.emplace(LineNumber, Filename);
+    I.DefLoc.emplace(LineNumber, Filename, IsFileInRootDir);
   else
-    I.Loc.emplace_back(LineNumber, Filename);
+    I.Loc.emplace_back(LineNumber, Filename, IsFileInRootDir);
 }
 
 static void populateFunctionInfo(FunctionInfo &I, const FunctionDecl *D,
                                  const FullComment *FC, int LineNumber,
-                                 StringRef Filename,
+                                 StringRef Filename, bool IsFileInRootDir,
                                  bool &IsInAnonymousNamespace) {
-  populateSymbolInfo(I, D, FC, LineNumber, Filename, IsInAnonymousNamespace);
+  populateSymbolInfo(I, D, FC, LineNumber, Filename, IsFileInRootDir,
+                     IsInAnonymousNamespace);
   if (const auto *T = getDeclForType(D->getReturnType())) {
     if (dyn_cast<EnumDecl>(T))
       I.ReturnType = TypeInfo(getUSRForDecl(T), T->getNameAsString(),
                               InfoType::IT_enum, getInfoRelativePath(T));
     else if (dyn_cast<RecordDecl>(T))
       I.ReturnType = TypeInfo(getUSRForDecl(T), T->getNameAsString(),
                               InfoType::IT_record, getInfoRelativePath(T));
   } else {
     I.ReturnType = TypeInfo(D->getReturnType().getAsString());
   }
   parseParameters(I, D);
 }
 
 std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
 emitInfo(const NamespaceDecl *D, const FullComment *FC, int LineNumber,
-         llvm::StringRef File, bool PublicOnly) {
+         llvm::StringRef File, bool IsFileInRootDir, bool PublicOnly) {
   auto I = llvm::make_unique<NamespaceInfo>();
   bool IsInAnonymousNamespace = false;
   populateInfo(*I, D, FC, IsInAnonymousNamespace);
   if (PublicOnly && ((IsInAnonymousNamespace || D->isAnonymousNamespace()) ||
                      !isPublic(D->getAccess(), D->getLinkageInternal())))
     return {};
   I->Name = D->isAnonymousNamespace()
                 ? llvm::SmallString<16>("@nonymous_namespace")
emitInfo(const NamespaceDecl *D, const FullComment *FC, int LineNumber,
   if (I->Namespace.empty())
     ParentI->Path = getInfoRelativePath(ParentI->Namespace);
   return {std::unique_ptr<Info>{std::move(I)},
           std::unique_ptr<Info>{std::move(ParentI)}};
 }
 
 std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
 emitInfo(const RecordDecl *D, const FullComment *FC, int LineNumber,
-         llvm::StringRef File, bool PublicOnly) {
+         llvm::StringRef File, bool IsFileInRootDir, bool PublicOnly) {
   auto I = llvm::make_unique<RecordInfo>();
   bool IsInAnonymousNamespace = false;
-  populateSymbolInfo(*I, D, FC, LineNumber, File, IsInAnonymousNamespace);
+  populateSymbolInfo(*I, D, FC, LineNumber, File, IsFileInRootDir,
+                     IsInAnonymousNamespace);
   if (PublicOnly && ((IsInAnonymousNamespace ||
                       !isPublic(D->getAccess(), D->getLinkageInternal()))))
     return {};
 
   I->TagType = D->getTagKind();
   parseFields(*I, D, PublicOnly);
   if (const auto *C = dyn_cast<CXXRecordDecl>(D)) {
     if (const TypedefNameDecl *TD = C->getTypedefNameForAnonDecl()) {
emitInfo(const RecordDecl *D, const FullComment *FC, int LineNumber,
   }
   default:
     llvm_unreachable("Invalid reference type for parent namespace");
   }
 }
 
 std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
 emitInfo(const FunctionDecl *D, const FullComment *FC, int LineNumber,
-         llvm::StringRef File, bool PublicOnly) {
+         llvm::StringRef File, bool IsFileInRootDir, bool PublicOnly) {
   FunctionInfo Func;
   bool IsInAnonymousNamespace = false;
-  populateFunctionInfo(Func, D, FC, LineNumber, File, IsInAnonymousNamespace);
+  populateFunctionInfo(Func, D, FC, LineNumber, File, IsFileInRootDir,
+                       IsInAnonymousNamespace);
   if (PublicOnly && ((IsInAnonymousNamespace ||
                       !isPublic(D->getAccess(), D->getLinkageInternal()))))
     return {};
 
   Func.Access = clang::AccessSpecifier::AS_none;
 
   // Wrap in enclosing scope
   auto ParentI = llvm::make_unique<NamespaceInfo>();
   if (!Func.Namespace.empty())
     ParentI->USR = Func.Namespace[0].USR;
   else
     ParentI->USR = SymbolID();
   if (Func.Namespace.empty())
     ParentI->Path = getInfoRelativePath(ParentI->Namespace);
   ParentI->ChildFunctions.emplace_back(std::move(Func));
   // Info is wrapped in its parent scope so it's returned in the second position
   return {nullptr, std::unique_ptr<Info>{std::move(ParentI)}};
 }
 
 std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
 emitInfo(const CXXMethodDecl *D, const FullComment *FC, int LineNumber,
-         llvm::StringRef File, bool PublicOnly) {
+         llvm::StringRef File, bool IsFileInRootDir, bool PublicOnly) {
   FunctionInfo Func;
   bool IsInAnonymousNamespace = false;
-  populateFunctionInfo(Func, D, FC, LineNumber, File, IsInAnonymousNamespace);
+  populateFunctionInfo(Func, D, FC, LineNumber, File, IsFileInRootDir,
+                       IsInAnonymousNamespace);
   if (PublicOnly && ((IsInAnonymousNamespace ||
                       !isPublic(D->getAccess(), D->getLinkageInternal()))))
     return {};
 
   Func.IsMethod = true;
 
   const NamedDecl *Parent = nullptr;
   if (const auto *SD =
if (Func.Namespace.empty())
     ParentI->Path = getInfoRelativePath(ParentI->Namespace);
   ParentI->ChildFunctions.emplace_back(std::move(Func));
   // Info is wrapped in its parent scope so it's returned in the second position
   return {nullptr, std::unique_ptr<Info>{std::move(ParentI)}};
 }
 
 std::pair<std::unique_ptr<Info>, std::unique_ptr<Info>>
 emitInfo(const EnumDecl *D, const FullComment *FC, int LineNumber,
-         llvm::StringRef File, bool PublicOnly) {
+         llvm::StringRef File, bool IsFileInRootDir, bool PublicOnly) {
   EnumInfo Enum;
   bool IsInAnonymousNamespace = false;
-  populateSymbolInfo(Enum, D, FC, LineNumber, File, IsInAnonymousNamespace);
+  populateSymbolInfo(Enum, D, FC, LineNumber, File, IsFileInRootDir,
+                     IsInAnonymousNamespace);
   if (PublicOnly && ((IsInAnonymousNamespace ||
                       !isPublic(D->getAccess(), D->getLinkageInternal()))))
     return {};
 
   Enum.Scoped = D->isScoped();
   parseEnumerators(Enum, D);
 
   // Put in global namespace

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp

static llvm::cl::opt<bool> DoxygenOnly(
     llvm::cl::desc("Use only doxygen-style comments to generate docs."),
     llvm::cl::init(false), 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));
 
+static llvm::cl::opt<std::string> RootDirectory(
+    "root-directory",
+    llvm::cl::desc(
+        "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));
+
+static llvm::cl::opt<std::string>
+    RepositoryUrl("repository",
+                  llvm::cl::desc("URL of repository that hosts code; used for "
+                                 "links to definition locations."),
+                  llvm::cl::cat(ClangDocCategory));
+
 enum OutputFormatTy {
   md,
   yaml,
   html,
 };
 
 static llvm::cl::opt<OutputFormatTy>
     FormatEnum("format", llvm::cl::desc("Format for outputted docs."),

 // documentation. The path returned is a composite of the output directory, the
 // info's relative path and name and the extension. The relative path should
 // have been constructed in the serialization phase.
 //
 // Example: Given the below, the <ext> path for class C will be
 // <root>/A/B/C.<ext>
 //
 // namespace A {
-// namesapce B {
+// namespace B {
 //
 // class C {};
 //
 // }
 // }
 llvm::Expected<llvm::SmallString<128>> getInfoOutputFile(StringRef Root,
                                                          StringRef RelativePath,
                                                          StringRef Name,
int main(int argc, const char **argv) {
 
   ArgumentsAdjuster ArgAdjuster;
   if (!DoxygenOnly)
     ArgAdjuster = combineAdjusters(
         getInsertArgumentAdjuster("-fparse-all-comments",
                                   tooling::ArgumentInsertPosition::END),
         ArgAdjuster);
 
+  llvm::SmallString<128> RootDir(RootDirectory);
+  if (RootDir.empty())
+    llvm::sys::fs::current_path(RootDir);
+
+  if (!RepositoryUrl.empty() && RepositoryUrl.find("http://") != 0 &&
+      RepositoryUrl.find("https://") != 0)
+    RepositoryUrl.insert(0, "http://");
+
   clang::doc::ClangDocContext CDCtx = {
       Exec->get()->getExecutionContext(),
       PublicOnly,
       OutDirectory,
-      {UserStylesheets.begin(), UserStylesheets.end()}};
+      {UserStylesheets.begin(), UserStylesheets.end()},
+      RootDir.str(),
+      RepositoryUrl};
 
   if (Format == "html") {
     void *MainAddr = (void *)(intptr_t)GetExecutablePath;
     std::string ClangDocPath = GetExecutablePath(argv[0], MainAddr);
     llvm::SmallString<128> DefaultStylesheet;
     llvm::sys::path::native(ClangDocPath, DefaultStylesheet);
     DefaultStylesheet = llvm::sys::path::parent_path(DefaultStylesheet);
     llvm::sys::path::append(DefaultStylesheet,

clang-tools-extra/unittests/clang-doc/HTMLGeneratorTest.cpp

 std::unique_ptr<Generator> getHTMLGenerator() {
   auto G = doc::findGeneratorByName("html");
   if (!G)
     return nullptr;
   return std::move(G.get());
 }
 
 ClangDocContext
-getClangDocContext(std::vector<std::string> UserStylesheets = {}) {
+getClangDocContext(std::vector<std::string> UserStylesheets = {},
+                   StringRef RepositoryUrl = "") {
   ClangDocContext CDCtx;
   CDCtx.UserStylesheets = {UserStylesheets.begin(), UserStylesheets.end()};
   CDCtx.UserStylesheets.insert(
       CDCtx.UserStylesheets.begin(),
       "../share/clang/clang-doc-default-stylesheet.css");
+  CDCtx.RepositoryUrl = RepositoryUrl;
   return CDCtx;
 }
 
 TEST(HTMLGeneratorTest, emitNamespaceHTML) {
   NamespaceInfo I;
   I.Name = "Namespace";
   I.Namespace.emplace_back(EmptySID, "A", InfoType::IT_namespace);
 

 }
 
 TEST(HTMLGeneratorTest, emitRecordHTML) {
   RecordInfo I;
   I.Name = "r";
   I.Path = "X/Y/Z";
   I.Namespace.emplace_back(EmptySID, "A", InfoType::IT_namespace);
 
-  I.DefLoc = Location(10, llvm::SmallString<16>{"test.cpp"});
+  I.DefLoc = Location(10, llvm::SmallString<16>{"dir/test.cpp"}, true);
   I.Loc.emplace_back(12, llvm::SmallString<16>{"test.cpp"});
 
   SmallString<16> PathTo;
   llvm::sys::path::native("path/to", PathTo);
   I.Members.emplace_back("int", "X/Y", "X", AccessSpecifier::AS_private);
   I.TagType = TagTypeKind::TTK_Class;
   I.Parents.emplace_back(EmptySID, "F", InfoType::IT_record, PathTo);
   I.VirtualParents.emplace_back(EmptySID, "G", InfoType::IT_record);
 
   I.ChildRecords.emplace_back(EmptySID, "ChildStruct", InfoType::IT_record);
   I.ChildFunctions.emplace_back();
   I.ChildFunctions.back().Name = "OneFunction";
   I.ChildEnums.emplace_back();
   I.ChildEnums.back().Name = "OneEnum";
 
   auto G = getHTMLGenerator();
   assert(G);
   std::string Buffer;
   llvm::raw_string_ostream Actual(Buffer);
-  ClangDocContext CDCtx = getClangDocContext();
+  ClangDocContext CDCtx = getClangDocContext({}, "https://www.repository.com");
   auto Err = G->generateDocForInfo(&I, Actual, CDCtx);
   assert(!Err);
   std::string Expected = R"raw(<!DOCTYPE html>
 <meta charset="utf-8"/>
 <title>class r</title>
 <link rel="stylesheet" href="../../../clang-doc-default-stylesheet.css"/>
 <div>
   <h1>class r</h1>
-  <p>Defined at line 10 of test.cpp</p>
+  <p>
+    Defined at line 
+    <a href="https://www.repository.com/dir/test.cpp#10">10</a>
+     of file 
+    <a href="https://www.repository.com/dir/test.cpp">test.cpp</a>
+  </p>
   <p>
     Inherits from 
     <a href="../../../path/to/F.html">F</a>
     , G
   </p>
   <h2>Members</h2>
   <ul>
     <li>
)raw";
   EXPECT_EQ(Expected, Actual.str());
 }
 
 TEST(HTMLGeneratorTest, emitFunctionHTML) {
   FunctionInfo I;
   I.Name = "f";
   I.Namespace.emplace_back(EmptySID, "A", InfoType::IT_namespace);
 
-  I.DefLoc = Location(10, llvm::SmallString<16>{"test.cpp"});
+  I.DefLoc = Location(10, llvm::SmallString<16>{"dir/test.cpp"}, false);
   I.Loc.emplace_back(12, llvm::SmallString<16>{"test.cpp"});
 
   SmallString<16> PathTo;
   llvm::sys::path::native("path/to", PathTo);
   I.ReturnType = TypeInfo(EmptySID, "float", InfoType::IT_default, PathTo);
   I.Params.emplace_back("int", PathTo, "P");
   I.IsMethod = true;
   I.Parent = Reference(EmptySID, "Parent", InfoType::IT_record);
 
   auto G = getHTMLGenerator();
   assert(G);
   std::string Buffer;
   llvm::raw_string_ostream Actual(Buffer);
-  ClangDocContext CDCtx = getClangDocContext();
+  ClangDocContext CDCtx = getClangDocContext({}, "https://www.repository.com");
   auto Err = G->generateDocForInfo(&I, Actual, CDCtx);
   assert(!Err);
   std::string Expected = R"raw(<!DOCTYPE html>
 <meta charset="utf-8"/>
 <title></title>
 <link rel="stylesheet" href="clang-doc-default-stylesheet.css"/>
 <div>
   <h3>f</h3>
   <p>
     <a href="path/to/float.html">float</a>
      f(
     <a href="path/to/int.html">int</a>
      P)
   </p>
-  <p>Defined at line 10 of test.cpp</p>
+  <p>Defined at line 10 of file dir/test.cpp</p>
 </div>
 )raw";
 
   EXPECT_EQ(Expected, Actual.str());
 }
 
 TEST(HTMLGeneratorTest, emitEnumHTML) {
   EnumInfo I;

 <meta charset="utf-8"/>
 <title></title>
 <link rel="stylesheet" href="clang-doc-default-stylesheet.css"/>
 <div>
   <h3>enum class e</h3>
   <ul>
     <li>X</li>
   </ul>
-  <p>Defined at line 10 of test.cpp</p>
+  <p>Defined at line 10 of file test.cpp</p>
 </div>
 )raw";
 
   EXPECT_EQ(Expected, Actual.str());
 }
 
 TEST(HTMLGeneratorTest, emitCommentHTML) {
   FunctionInfo I;
TEST(HTMLGeneratorTest, emitCommentHTML) {
   assert(!Err);
   std::string Expected = R"raw(<!DOCTYPE html>
 <meta charset="utf-8"/>
 <title></title>
 <link rel="stylesheet" href="clang-doc-default-stylesheet.css"/>
 <div>
   <h3>f</h3>
   <p>void f(int I, int J)</p>
-  <p>Defined at line 10 of test.cpp</p>
+  <p>Defined at line 10 of file test.cpp</p>
   <div>
     <div>
       <p> Brief description.</p>
       <p> Extended description that continues onto the next line.</p>
       <p> Comment with html entities: &amp;, &lt;, &gt;, &quot;, &apos;.</p>
     </div>
   </div>
 </div>
 )raw";
 
   EXPECT_EQ(Expected, Actual.str());
 }
 
 } // namespace doc
 } // namespace clang

clang-tools-extra/unittests/clang-doc/SerializeTest.cpp

class ClangDocSerializeTestVisitor
   }
 
 public:
   ClangDocSerializeTestVisitor(EmittedInfoList &EmittedInfos, bool Public)
       : EmittedInfos(EmittedInfos), Public(Public) {}
 
   template <typename T> bool mapDecl(const T *D) {
     auto I = serialize::emitInfo(D, getComment(D), /*Line=*/0,
-                                 /*File=*/"test.cpp", Public);
+                                 /*File=*/"test.cpp", true, Public);
     if (I.first)
       EmittedInfos.emplace_back(std::move(I.first));
     if (I.second)
       EmittedInfos.emplace_back(std::move(I.second));
     return true;
   }
 
   bool VisitNamespaceDecl(const NamespaceDecl *D) { return mapDecl(D); }