[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 ↗

(On Diff #212457)

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 ↗

(On Diff #212457)

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 ↗

(On Diff #212457)

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 ↗

(On Diff #212457)

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 ↗

(On Diff #212457)

"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 ↗

(On Diff #212457)

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 ↗

(On Diff #212457)

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 ↗

(On Diff #212457)

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

103–104 ↗

(On Diff #212457)

Leave a comment to that effect, then.

40 ↗

(On Diff #213169)

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

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

228 ↗

(On Diff #212457)

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

76 ↗

(On Diff #213169)

Can we call this --source-root?

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

385 ↗

(On Diff #213776)

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

396 ↗

(On Diff #213776)

Comment

[DiegoAstiazaran]

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

[DiegoAstiazaran]

Rebase to master

[juliehockett]

LGTM

clang-tools-extra/trunk/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/trunk/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/trunk/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.back()->Attributes.try_emplace("id", "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.back()->Attributes.try_emplace("id", "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,
+                    llvm::Optional<StringRef> RepositoryUrl = None) {
+  if (!L.IsFileInRootDir || !RepositoryUrl)
     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.getValue());
+  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));
+  // The links to a specific line in the source code use the github /
+  // googlesource notation so it won't work for all hosting pages.
+  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::vector<std::unique_ptr<TagNode>>
 genCommonFileNodes(StringRef Title, StringRef InfoPath,
                    const ClangDocContext &CDCtx) {
   std::vector<std::unique_ptr<TagNode>> Out;
   auto MetaNode = llvm::make_unique<TagNode>(HTMLTag::TAG_META);
   MetaNode->Attributes.try_emplace("charset", "utf-8");
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));
   Out.back()->Attributes.try_emplace("id",
                                      llvm::toHex(llvm::toStringRef(I.USR)));
 
   std::unique_ptr<TagNode> Node = genEnumMembersBlock(I.Members);
   if (Node)
     Out.emplace_back(std::move(Node));
 
-  if (I.DefLoc)
+  if (I.DefLoc) {
+    if (!CDCtx.RepositoryUrl)
       Out.emplace_back(writeFileDefinition(I.DefLoc.getValue()));
+    else
+      Out.emplace_back(writeFileDefinition(
+          I.DefLoc.getValue(), StringRef{CDCtx.RepositoryUrl.getValue()}));
+  }
 
   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));
   // USR is used as id for functions instead of name to disambiguate function
   // overloads.
   Out.back()->Attributes.try_emplace("id",
                                      llvm::toHex(llvm::toStringRef(I.USR)));
 
   Out.emplace_back(llvm::make_unique<TagNode>(HTMLTag::TAG_P));
if (&P != I.Params.begin())
       FunctionHeader->Children.emplace_back(llvm::make_unique<TextNode>(", "));
     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)
+  if (I.DefLoc) {
+    if (!CDCtx.RepositoryUrl)
       Out.emplace_back(writeFileDefinition(I.DefLoc.getValue()));
+    else
+      Out.emplace_back(writeFileDefinition(
+          I.DefLoc.getValue(), StringRef{CDCtx.RepositoryUrl.getValue()}));
+  }
 
   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, Index &InfoIndex, std::string &InfoTitle) {
+genHTML(const NamespaceInfo &I, Index &InfoIndex, const ClangDocContext &CDCtx,
+        std::string &InfoTitle) {
   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);
 
   if (!I.ChildNamespaces.empty())
     InfoIndex.Children.emplace_back("Namespaces", "Namespaces");
   if (!I.ChildRecords.empty())
     InfoIndex.Children.emplace_back("Records", "Records");
   if (!I.ChildFunctions.empty())
     InfoIndex.Children.emplace_back(
         genInfoIndexItem(I.ChildFunctions, "Functions"));
   if (!I.ChildEnums.empty())
     InfoIndex.Children.emplace_back(genInfoIndexItem(I.ChildEnums, "Enums"));
 
   return Out;
 }
 
 static std::vector<std::unique_ptr<TagNode>>
-genHTML(const RecordInfo &I, Index &InfoIndex, std::string &InfoTitle) {
+genHTML(const RecordInfo &I, Index &InfoIndex, const ClangDocContext &CDCtx,
+        std::string &InfoTitle) {
   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)
+  if (I.DefLoc) {
+    if (!CDCtx.RepositoryUrl)
       Out.emplace_back(writeFileDefinition(I.DefLoc.getValue()));
+    else
+      Out.emplace_back(writeFileDefinition(
+          I.DefLoc.getValue(), StringRef{CDCtx.RepositoryUrl.getValue()}));
+  }
 
   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, Index &InfoIndex, 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);
 
   if (!I.Members.empty())
     InfoIndex.Children.emplace_back("Members", "Members");
   if (!I.ChildRecords.empty())
     InfoIndex.Children.emplace_back("Records", "Records");
   if (!I.ChildFunctions.empty())
     InfoIndex.Children.emplace_back(

 llvm::Error HTMLGenerator::generateDocForInfo(Info *I, llvm::raw_ostream &OS,
                                               const ClangDocContext &CDCtx) {
   HTMLFile F;
   std::string InfoTitle;
   auto MainContentNode = llvm::make_unique<TagNode>(HTMLTag::TAG_DIV);
   Index InfoIndex;
   switch (I->IT) {
   case InfoType::IT_namespace: {
-    std::vector<std::unique_ptr<TagNode>> Nodes = genHTML(
-        *static_cast<clang::doc::NamespaceInfo *>(I), InfoIndex, InfoTitle);
+    std::vector<std::unique_ptr<TagNode>> Nodes =
+        genHTML(*static_cast<clang::doc::NamespaceInfo *>(I), InfoIndex, 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), InfoIndex, InfoTitle);
+        *static_cast<clang::doc::RecordInfo *>(I), InfoIndex, 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/trunk/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/trunk/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;
+  llvm::SmallString<128> File =
+      getFile(D, D->getASTContext(), CDCtx.SourceRoot, 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);
+  // replace_path_prefix removes the exact prefix provided. The result of
+  // calling that function on ("A/B/C.c", "A/B", "") would be "/C.c", which
+  // starts with a / that is not needed. This is why we fix Prefix so it always
+  // ends with a / and the result has the desired format.
+  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/trunk/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)

 // 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 {
   ClangDocContext() = default;
   ClangDocContext(tooling::ExecutionContext *ECtx, bool PublicOnly,
-                  StringRef OutDirectory,
+                  StringRef OutDirectory, StringRef SourceRoot,
+                  StringRef RepositoryUrl,
                   std::vector<std::string> UserStylesheets,
-                  std::vector<std::string> JsScripts)
-      : ECtx(ECtx), PublicOnly(PublicOnly), OutDirectory(OutDirectory),
-        UserStylesheets(UserStylesheets), JsScripts(JsScripts) {}
+                  std::vector<std::string> JsScripts);
   tooling::ExecutionContext *ECtx;
-  bool PublicOnly;
-  std::string OutDirectory;
+  bool PublicOnly; // Indicates if only public declarations are documented.
+  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
+                            // the file is in this dir.
+  // URL of repository that hosts code used for links to definition locations.
+  llvm::Optional<std::string> RepositoryUrl;
   // Path of CSS stylesheets that will be copied to OutDirectory and used to
   // style all HTML files.
   std::vector<std::string> UserStylesheets;
   // JavaScript files that will be imported in allHTML file.
   std::vector<std::string> JsScripts;
   // Other files that should be copied to OutDirectory, besides UserStylesheets.
   std::vector<std::string> FilesToCopy;
   Index Idx;
 };
 
 } // namespace doc
 } // namespace clang
 
 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_REPRESENTATION_H

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

 }
 
 void Index::sort() {
   std::sort(Children.begin(), Children.end());
   for (auto &C : Children)
     C.sort();
 }
 
+ClangDocContext::ClangDocContext(tooling::ExecutionContext *ECtx,
+                                 bool PublicOnly, StringRef OutDirectory,
+                                 StringRef SourceRoot, StringRef RepositoryUrl,
+                                 std::vector<std::string> UserStylesheets,
+                                 std::vector<std::string> JsScripts)
+    : ECtx(ECtx), PublicOnly(PublicOnly), OutDirectory(OutDirectory),
+      SourceRoot(SourceRoot), UserStylesheets(UserStylesheets),
+      JsScripts(JsScripts) {
+  if (!RepositoryUrl.empty()) {
+    this->RepositoryUrl = RepositoryUrl;
+    if (!RepositoryUrl.empty() && RepositoryUrl.find("http://") != 0 &&
+        RepositoryUrl.find("https://") != 0)
+      this->RepositoryUrl->insert(0, "https://");
+  }
+}
+
 } // namespace doc
 } // namespace clang

clang-tools-extra/trunk/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/trunk/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/trunk/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> 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));
+
+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));
+
 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> SourceRootDir;
+  // Check if the --source-root flag has a value
+  if (SourceRoot.empty())
+    // If it's empty the current path is used as the default
+    llvm::sys::fs::current_path(SourceRootDir);
+
   clang::doc::ClangDocContext CDCtx = {
       Exec->get()->getExecutionContext(),
       PublicOnly,
       OutDirectory,
+      SourceRootDir.str(),
+      RepositoryUrl,
       {UserStylesheets.begin(), UserStylesheets.end()},
       {"index.js", "index_json.js"}};
 
   if (Format == "html") {
     void *MainAddr = (void *)(intptr_t)GetExecutablePath;
     std::string ClangDocPath = GetExecutablePath(argv[0], MainAddr);
     llvm::SmallString<128> AssetsPath;
     llvm::sys::path::native(ClangDocPath, AssetsPath);

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

 
 Options
 -------
 
 :program:`clang-doc` offers the following options:
 
 .. code-block:: console
 
-  $ clang-doc --help
+  $ clang-doc --help
   USAGE: clang-doc [options] <source0> [... <sourceN>]
 
   OPTIONS:
 
   Generic Options:
 
     -help                      - Display available options (-help-hidden for more)
     -help-list                 - Display list of available options (-help-list-hidden for more)
     -version                   - Display the version of this program
 
   clang-doc options:
 
-    -doxygen                   - Use only doxygen-style comments to generate docs.
-    -dump                      - Dump intermediate results to bitcode file.
-    -extra-arg=<string>        - Additional argument to append to the compiler command line
-    -extra-arg-before=<string> - Additional argument to prepend to the compiler command line
-    --format=<value>           - Format for outputted docs.
-      =yaml                    -   Documentation in YAML format.
-      =md                      -   Documentation in MD format.
-      =html                    -   Documentation in HTML format.
-    -output=<string>           - Directory for outputting generated files.
-    -p=<string>                - Build path
-    --public                   - Document only public declarations.
-    --stylesheets=<string>     - CSS stylesheets to extend the default styles.
+    --doxygen                   - Use only doxygen-style comments to generate docs.
+    --extra-arg=<string>        - Additional argument to append to the compiler command line
+    --extra-arg-before=<string> - Additional argument to prepend to the compiler command line
+    --format=<value>            - Format for outputted docs.
+      =yaml                     -   Documentation in YAML format.
+      =md                       -   Documentation in MD format.
+      =html                     -   Documentation in HTML format.
+    --ignore-map-errors         - Continue if files are not mapped correctly.
+    --output=<string>           - Directory for outputting generated files.
+    -p=<string>                 - Build path
+    --public                    - Document only public declarations.
+    --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.
+    --stylesheets=<string>      - CSS stylesheets to extend the default styles.
 
-``stylesheets`` should only be used if ``format`` is set to ``html``.
+The following flags shoud only be used if ``format`` is set to ``html``:
+- ``repository``
+- ``source-root``
+- ``stylesheets``

clang-tools-extra/trunk/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 = {}) {
-  ClangDocContext CDCtx;
-  CDCtx.UserStylesheets = {UserStylesheets.begin(), UserStylesheets.end()};
+getClangDocContext(std::vector<std::string> UserStylesheets = {},
+                   StringRef RepositoryUrl = "") {
+  ClangDocContext CDCtx{{}, {}, {}, {}, RepositoryUrl, UserStylesheets, {}};
   CDCtx.UserStylesheets.insert(
       CDCtx.UserStylesheets.begin(),
       "../share/clang/clang-doc-default-stylesheet.css");
   CDCtx.JsScripts.emplace_back("index.js");
   return CDCtx;
 }
 
 TEST(HTMLGeneratorTest, emitNamespaceHTML) {

 }
 
 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({}, "http://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"/>
 <script src="../../../index.js"></script>
 <div id="index" path="X/Y/Z"></div>
<ul>
           <a href="#0000000000000000000000000000000000000000">OneEnum</a>
         </span>
       </li>
     </ul>
   </li>
 </ul>
 <div>
   <h1>class r</h1>
-  <p>Defined at line 10 of test.cpp</p>
+  <p>
+    Defined at line 
+    <a href="http://www.repository.com/dir/test.cpp#10">10</a>
+     of file 
+    <a href="http://www.repository.com/dir/test.cpp">test.cpp</a>
+  </p>
   <p>
     Inherits from 
     <a href="../../../path/to/F.html">F</a>
     , G
   </p>
   <h2 id="Members">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"/>
 <script src="index.js"></script>
 <div id="index" path=""></div>
 <div>
   <h3 id="0000000000000000000000000000000000000000">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;
   I.Name = "e";
   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>{"test.cpp"}, true);
   I.Loc.emplace_back(12, llvm::SmallString<16>{"test.cpp"});
 
   I.Members.emplace_back("X");
   I.Scoped = true;
 
   auto G = getHTMLGenerator();
   assert(G);
   std::string Buffer;
   llvm::raw_string_ostream Actual(Buffer);
-  ClangDocContext CDCtx = getClangDocContext();
+  ClangDocContext CDCtx = getClangDocContext({}, "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"/>
 <script src="index.js"></script>
 <div id="index" path=""></div>
 <div>
   <h3 id="0000000000000000000000000000000000000000">enum class e</h3>
   <ul>
     <li>X</li>
   </ul>
-  <p>Defined at line 10 of test.cpp</p>
+  <p>
+    Defined at line 
+    <a href="https://www.repository.com/test.cpp#10">10</a>
+     of file 
+    <a href="https://www.repository.com/test.cpp">test.cpp</a>
+  </p>
 </div>
 )raw";
 
   EXPECT_EQ(Expected, Actual.str());
 }
 
 TEST(HTMLGeneratorTest, emitCommentHTML) {
   FunctionInfo I;

 <meta charset="utf-8"/>
 <title></title>
 <link rel="stylesheet" href="clang-doc-default-stylesheet.css"/>
 <script src="index.js"></script>
 <div id="index" path=""></div>
 <div>
   <h3 id="0000000000000000000000000000000000000000">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/trunk/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); }