[clang-doc] [feat] add --repository-line-prefix argument

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

@@ -491,9 +491,9 @@ genReferencesBlock(const std::vector<Reference> &References,
   return Out;
 }
 
-static std::unique_ptr<TagNode>
-writeFileDefinition(const Location &L,
-                    std::optional<StringRef> RepositoryUrl = std::nullopt) {
+static std::unique_ptr<TagNode> writeFileDefinition(
+    const Location &L, std::optional<StringRef> RepositoryUrl = std::nullopt,
+    std::optional<StringRef> RepositoryLinePrefix = std::nullopt) {
   if (!L.IsFileInRootDir && !RepositoryUrl)
     return std::make_unique<TagNode>(
         HTMLTag::TAG_P, "Defined at line " + std::to_string(L.LineNumber) +
@@ -514,17 +514,21 @@ writeFileDefinition(const Location &L,
   Node->Children.emplace_back(std::make_unique<TextNode>("Defined at line "));
   auto LocNumberNode =
       std::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.
-  // FIXME: we probably should have a configuration setting for line number
-  // rendering in the HTML. For example, GitHub uses #L22, while googlesource
-  // uses #22 for line numbers.
-  LocNumberNode->Attributes.emplace_back(
-      "href", (FileURL + "#" + std::to_string(L.LineNumber)).str());
+
+  std::string LineAnchor = "#";
+
+  if (RepositoryLinePrefix)
+    LineAnchor += RepositoryLinePrefix.value().str();
+
+  LineAnchor += std::to_string(L.LineNumber);
+
+  LocNumberNode->Attributes.emplace_back("href", (FileURL + LineAnchor).str());
   Node->Children.emplace_back(std::move(LocNumberNode));
   Node->Children.emplace_back(std::make_unique<TextNode>(" of file "));
+
   auto LocFileNode = std::make_unique<TagNode>(
       HTMLTag::TAG_A, llvm::sys::path::filename(FileURL));
+
   LocFileNode->Attributes.emplace_back("href", std::string(FileURL));
   Node->Children.emplace_back(std::move(LocFileNode));
   return Node;
@@ -750,11 +754,15 @@ genHTML(const EnumInfo &I, const ClangDocContext &CDCtx) {
   Out.emplace_back(std::move(Table));
 
   if (I.DefLoc) {
-    if (!CDCtx.RepositoryUrl)
-      Out.emplace_back(writeFileDefinition(*I.DefLoc));
-    else
-      Out.emplace_back(
-          writeFileDefinition(*I.DefLoc, StringRef{*CDCtx.RepositoryUrl}));
+    std::optional<StringRef> RepoUrl;
+    std::optional<StringRef> RepoLinePrefix;
+
+    if (CDCtx.RepositoryUrl)
+      RepoUrl = StringRef{*CDCtx.RepositoryUrl};
+    if (CDCtx.RepositoryLinePrefix)
+      RepoLinePrefix = StringRef{*CDCtx.RepositoryLinePrefix};
+
+    Out.emplace_back(writeFileDefinition(*I.DefLoc, RepoUrl, RepoLinePrefix));
   }
 
   std::string Description;
@@ -799,11 +807,15 @@ genHTML(const FunctionInfo &I, const ClangDocContext &CDCtx,
   FunctionHeader->Children.emplace_back(std::make_unique<TextNode>(")"));
 
   if (I.DefLoc) {
-    if (!CDCtx.RepositoryUrl)
-      Out.emplace_back(writeFileDefinition(*I.DefLoc));
-    else
-      Out.emplace_back(writeFileDefinition(
-          *I.DefLoc, StringRef{*CDCtx.RepositoryUrl}));
+    std::optional<StringRef> RepoUrl;
+    std::optional<StringRef> RepoLinePrefix;
+
+    if (CDCtx.RepositoryUrl)
+      RepoUrl = StringRef{*CDCtx.RepositoryUrl};
+    if (CDCtx.RepositoryLinePrefix)
+      RepoLinePrefix = StringRef{*CDCtx.RepositoryLinePrefix};
+
+    Out.emplace_back(writeFileDefinition(*I.DefLoc, RepoUrl, RepoLinePrefix));
   }
 
   std::string Description;
@@ -866,11 +878,15 @@ genHTML(const RecordInfo &I, Index &InfoIndex, const ClangDocContext &CDCtx,
   Out.emplace_back(std::make_unique<TagNode>(HTMLTag::TAG_H1, InfoTitle));
 
   if (I.DefLoc) {
-    if (!CDCtx.RepositoryUrl)
-      Out.emplace_back(writeFileDefinition(*I.DefLoc));
-    else
-      Out.emplace_back(writeFileDefinition(
-          *I.DefLoc, StringRef{*CDCtx.RepositoryUrl}));
+    std::optional<StringRef> RepoUrl;
+    std::optional<StringRef> RepoLinePrefix;
+
+    if (CDCtx.RepositoryUrl)
+      RepoUrl = StringRef{*CDCtx.RepositoryUrl};
+    if (CDCtx.RepositoryLinePrefix)
+      RepoLinePrefix = StringRef{*CDCtx.RepositoryLinePrefix};
+
+    Out.emplace_back(writeFileDefinition(*I.DefLoc, RepoUrl, RepoLinePrefix));
   }
 
   std::string Description;

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

@@ -57,7 +57,12 @@ static void writeFileDefinition(const ClangDocContext &CDCtx, const Location &L,
     OS << "*Defined at " << L.Filename << "#" << std::to_string(L.LineNumber)
        << "*";
   } else {
-    OS << "*Defined at [" << L.Filename << "#" << std::to_string(L.LineNumber)
+    OS << "*Defined at [" << L.Filename << "#";
+
+    if (!CDCtx.RepositoryLinePrefix) 
+      OS << StringRef{*CDCtx.RepositoryLinePrefix};  
+
+    OS << std::to_string(L.LineNumber)
        << "](" << StringRef{*CDCtx.RepositoryUrl}
        << llvm::sys::path::relative_path(L.Filename) << "#"
        << std::to_string(L.LineNumber) << ")"

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

@@ -368,6 +368,7 @@ ClangDocContext::ClangDocContext(tooling::ExecutionContext *ECtx,
                                  StringRef ProjectName, bool PublicOnly,
                                  StringRef OutDirectory, StringRef SourceRoot,
                                  StringRef RepositoryUrl,
+                                 StringRef RepositoryLinePrefix,
                                  std::vector<std::string> UserStylesheets)
     : ECtx(ECtx), ProjectName(ProjectName), PublicOnly(PublicOnly),
       OutDirectory(OutDirectory), UserStylesheets(UserStylesheets) {
@@ -381,6 +382,9 @@ ClangDocContext::ClangDocContext(tooling::ExecutionContext *ECtx,
     if (!RepositoryUrl.empty() && !RepositoryUrl.starts_with("http://") &&
         !RepositoryUrl.starts_with("https://"))
       this->RepositoryUrl->insert(0, "https://");
+
+    if (!RepositoryLinePrefix.empty())
+      this->RepositoryLinePrefix = std::string(RepositoryLinePrefix);
   }
 }
 

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

@@ -508,6 +508,7 @@ struct ClangDocContext {
   ClangDocContext(tooling::ExecutionContext *ECtx, StringRef ProjectName,
                   bool PublicOnly, StringRef OutDirectory, StringRef SourceRoot,
                   StringRef RepositoryUrl,
+                  StringRef RepositoryCodeLinePrefix,
                   std::vector<std::string> UserStylesheets);
   tooling::ExecutionContext *ECtx;
   std::string ProjectName; // Name of project clang-doc is documenting.
@@ -518,10 +519,12 @@ struct ClangDocContext {
                             // the file is in this dir.
   // URL of repository that hosts code used for links to definition locations.
   std::optional<std::string> RepositoryUrl;
+  // Prefix of line code for repository.
+  std::optional<std::string> RepositoryLinePrefix;
   // 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.
+  // JavaScript files that will be imported in all HTML file.
   std::vector<std::string> JsScripts;
   Index Idx;
 };

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

@@ -99,6 +99,12 @@ URL of repository that hosts code.
 Used for links to definition locations.)"),
                   llvm::cl::cat(ClangDocCategory));
 
+static llvm::cl::opt<std::string>
+    RepositoryCodeLinePrefix("repository-line-prefix", llvm::cl::desc(R"(
+Prefix of line code for repository.
+)"),
+                             llvm::cl::cat(ClangDocCategory));
+
 enum OutputFormatTy {
   md,
   yaml,
@@ -141,8 +147,7 @@ llvm::Error getAssetFiles(clang::doc::ClangDocContext &CDCtx) {
   using DirIt = llvm::sys::fs::directory_iterator;
   std::error_code FileErr;
   llvm::SmallString<128> FilePath(UserAssetPath);
-  for (DirIt DirStart = DirIt(UserAssetPath, FileErr),
-                   DirEnd;
+  for (DirIt DirStart = DirIt(UserAssetPath, FileErr), DirEnd;
        !FileErr && DirStart != DirEnd; DirStart.increment(FileErr)) {
     FilePath = DirStart->path();
     if (llvm::sys::fs::is_regular_file(FilePath)) {
@@ -268,8 +273,8 @@ Example usage for a project using a compile commands database:
       OutDirectory,
       SourceRoot,
       RepositoryUrl,
-      {UserStylesheets.begin(), UserStylesheets.end()}
-  };
+      RepositoryCodeLinePrefix,
+      {UserStylesheets.begin(), UserStylesheets.end()}};
 
   if (Format == "html") {
     if (auto Err = getHtmlAssetFiles(argv[0], CDCtx)) {