NOT READY FOR REVIEW Nothing to see here, just exporting to show this to someone.

[dblaikie]

Rather than sending a review to the lists that you don't need review for, you can create draft reviews that send no mail and share them manually with your intended audience, discussed/documented here: https://llvm.org/docs/Phabricator.html#requesting-a-review-via-the-command-line

clang-tools-extra/clangd/CodeCompletionStrings.h

 /// Returns empty string when no comment is available.
 /// If \p CommentsFromHeaders parameter is set, only comments from the main
 /// file will be returned. It is used to workaround crashes when parsing
 /// comments in the stale headers, coming from completion preamble.
 std::string getDocComment(const ASTContext &Ctx,
                           const CodeCompletionResult &Result,
                           bool CommentsFromHeaders);
 
-/// Similar to getDocComment, but returns the comment for a NamedDecl.
-std::string getDeclComment(const ASTContext &Ctx, const NamedDecl &D);
+/// Similar to getDocComment, but returns the comment for a NamedDecl. The
+/// optional CommentRange argument is set to the location of the returned
+/// comment.
+std::string getDeclComment(const ASTContext &Ctx, const NamedDecl &D,
+                           SourceRange *CommentRange = nullptr);
 
 /// Formats the signature for an item, as a display string and snippet.
 /// e.g. for const_reference std::vector<T>::at(size_type) const, this returns:
 ///   *Signature = "(size_type) const"
 ///   *Snippet = "(${1:size_type})"
 /// If set, RequiredQualifiers is the text that must be typed before the name.
 /// e.g "Base::" when calling a base class member function that's hidden.
 ///

clang-tools-extra/clangd/CodeCompletionStrings.cpp

std::string getDocComment(const ASTContext &Ctx,
   // contain a pattern for ObjC properties. Unfortunately, there is no API to
   // get this declaration, so we don't show documentation in that case.
   if (Result.Kind != CodeCompletionResult::RK_Declaration)
     return "";
   return Result.getDeclaration() ? getDeclComment(Ctx, *Result.getDeclaration())
                                  : "";
 }
 
-std::string getDeclComment(const ASTContext &Ctx, const NamedDecl &Decl) {
+std::string getDeclComment(const ASTContext &Ctx, const NamedDecl &Decl,
+                           SourceRange *CommentRange) {
   if (isa<NamespaceDecl>(Decl)) {
     // Namespaces often have too many redecls for any particular redecl comment
     // to be useful. Moreover, we often confuse file headers or generated
     // comments with namespace comments. Therefore we choose to just ignore
     // the comments for namespaces.
     return "";
   }
   const RawComment *RC = getCompletionComment(Ctx, &Decl);
   if (!RC)
     return "";
   // Sanity check that the comment does not come from the PCH. We choose to not
   // write them into PCH, because they are racy and slow to load.
   assert(!Ctx.getSourceManager().isLoadedSourceLocation(RC->getBeginLoc()));
   std::string Doc =
       RC->getFormattedText(Ctx.getSourceManager(), Ctx.getDiagnostics());
   if (!looksLikeDocComment(Doc))
     return "";
   // Clang requires source to be UTF-8, but doesn't enforce this in comments.
   if (!llvm::json::isUTF8(Doc))
     Doc = llvm::json::fixUTF8(Doc);
+  if (CommentRange) {
+    *CommentRange = RC->getSourceRange();
+  }
   return Doc;
 }
 
 void getSignature(const CodeCompletionString &CCS, std::string *Signature,
                   std::string *Snippet, std::string *RequiredQualifiers,
                   bool CompletingPattern) {
   // Placeholder with this index will be ${0:…} to mark final cursor position.
   // Usually we do not add $0, so the cursor is placed at end of completed text.

clang-tools-extra/clangd/Hover.h

struct HoverInfo {
   /// Remaining named contexts in symbol's qualified name, empty string means
   /// symbol is not local.
   std::string LocalScope;
   /// Name of the symbol, does not contain any "::".
   std::string Name;
   llvm::Optional<Range> SymRange;
   index::SymbolKind Kind = index::SymbolKind::Unknown;
   std::string Documentation;
+  // Location of the documentation in the source code, if any. This can be used
+  // to linkify that part of hover card or check permissions.
+  Location DocumentationLocation;
   /// Source code containing the definition of the symbol.
   std::string Definition;
   const char *DefinitionLanguage = "cpp";
   /// Access specifier for declarations inside class/struct/unions, empty for
   /// others.
   std::string AccessSpecifier;
   /// Pretty-printed variable type.
   /// Set only for variables.

clang-tools-extra/clangd/Hover.cpp

if (!SymbolCollector::shouldCollectSymbol(ND, ND.getASTContext(),
                                             /*IsMainFileOnly=*/false))
     return;
   auto ID = getSymbolID(&ND);
   if (!ID)
     return;
   LookupRequest Req;
   Req.IDs.insert(ID);
   Index->lookup(Req, [&](const Symbol &S) {
+    // FIXME: We should fill Hover.DocumentationLocation as well, but currently
+    // we do not have that information in the index.
     Hover.Documentation = std::string(S.Documentation);
   });
 }
 
 // Default argument might exist but be unavailable, in the case of unparsed
 // arguments for example. This function returns the default argument if it is
 // available.
 const Expr *getDefaultArg(const ParmVarDecl *PVD) {
if (CMD->getDeclName().isIdentifier() && !CMD->isStatic() &&
         return llvm::formatv("Trivial accessor for `{0}`.", *GetterField);
       if (const auto SetterField = setterVariableName(CMD))
         return llvm::formatv("Trivial setter for `{0}`.", *SetterField);
     }
   }
   return "";
 }
 
+void addDocumentationToHoverInfo(const NamedDecl *D, const ASTContext &ASTCtx,
+                                 HoverInfo &HI) {
+  const auto &SM = ASTCtx.getSourceManager();
+
+  SourceRange DocumentationRange;
+  HI.Documentation = getDeclComment(ASTCtx, *D, &DocumentationRange);
+
+  if (DocumentationRange.isValid()) {
+    const auto MainFilePath =
+        getCanonicalPath(SM.getFileEntryForID(SM.getMainFileID()), SM);
+    if (MainFilePath) {
+      const auto Loc =
+          makeLocation(ASTCtx, DocumentationRange.getBegin(), *MainFilePath);
+      if (Loc)
+        HI.DocumentationLocation = *Loc;
+    }
+  }
+}
+
 /// Generate a \p Hover object given the declaration \p D.
 HoverInfo getHoverContents(const NamedDecl *D, const PrintingPolicy &PP,
                            const SymbolIndex *Index) {
   HoverInfo HI;
   const ASTContext &Ctx = D->getASTContext();
 
   HI.AccessSpecifier = getAccessSpelling(D->getAccess()).str();
   HI.NamespaceScope = getNamespaceScope(D);
   if (!HI.NamespaceScope->empty())
     HI.NamespaceScope->append("::");
   HI.LocalScope = getLocalScope(D);
   if (!HI.LocalScope.empty())
     HI.LocalScope.append("::");
 
   HI.Name = printName(Ctx, *D);
   const auto *CommentD = getDeclForComment(D);
-  HI.Documentation = getDeclComment(Ctx, *CommentD);
+  addDocumentationToHoverInfo(CommentD, Ctx, HI);
   enhanceFromIndex(HI, *CommentD, Index);
   if (HI.Documentation.empty())
     HI.Documentation = synthesizeDocumentation(D);
 
   HI.Kind = index::getSymbolInfo(D).Kind;
 
   // Fill in template params.
   if (const TemplateDecl *TD = D->getDescribedTemplate()) {
HoverInfo getDeducedTypeHoverContents(QualType QT, const syntax::Token &Tok,
 
   if (QT->isUndeducedAutoType()) {
     HI.Definition = "/* not deduced */";
   } else {
     HI.Definition = printType(QT, PP);
 
     if (const auto *D = QT->getAsTagDecl()) {
       const auto *CommentD = getDeclForComment(D);
-      HI.Documentation = getDeclComment(ASTCtx, *CommentD);
+      addDocumentationToHoverInfo(CommentD, ASTCtx, HI);
       enhanceFromIndex(HI, *CommentD, Index);
     }
   }
 
   return HI;
 }
 
 bool isLiteral(const Expr *E) {

clang-tools-extra/clangd/SourceCode.h

 //
 //===----------------------------------------------------------------------===//
 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_SOURCECODE_H
 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_SOURCECODE_H
 
 #include "Protocol.h"
 #include "support/Context.h"
 #include "support/ThreadsafeFS.h"
+#include "clang/AST/ASTContext.h"
 #include "clang/Basic/Diagnostic.h"
 #include "clang/Basic/LangOptions.h"
 #include "clang/Basic/SourceLocation.h"
 #include "clang/Basic/SourceManager.h"
 #include "clang/Format/Format.h"
 #include "clang/Tooling/Core/Replacement.h"
 #include "clang/Tooling/Syntax/Tokens.h"
 #include "llvm/ADT/StringRef.h"

 /// Infers whether this is a header from the FileName and LangOpts (if
 /// presents).
 bool isHeaderFile(llvm::StringRef FileName,
                   llvm::Optional<LangOptions> LangOpts = llvm::None);
 
 /// Returns true if the given location is in a generated protobuf file.
 bool isProtoFile(SourceLocation Loc, const SourceManager &SourceMgr);
 
+// Expects Loc to be a SpellingLocation, will bail out otherwise as it can't
+// figure out a filename.
+llvm::Optional<Location> makeLocation(const ASTContext &AST, SourceLocation Loc,
+                                      llvm::StringRef TUPath);
+
 } // namespace clangd
 } // namespace clang
 #endif

clang-tools-extra/clangd/SourceCode.cpp

bool isProtoFile(SourceLocation Loc, const SourceManager &SM) {
   auto FID = SM.getFileID(Loc);
   // All proto generated headers should start with this line.
   static const char *PROTO_HEADER_COMMENT =
       "// Generated by the protocol buffer compiler.  DO NOT EDIT!";
   // Double check that this is an actual protobuf header.
   return SM.getBufferData(FID).startswith(PROTO_HEADER_COMMENT);
 }
 
+llvm::Optional<Location> makeLocation(const ASTContext &AST, SourceLocation Loc,
+                                      llvm::StringRef TUPath) {
+  const auto &SM = AST.getSourceManager();
+  const FileEntry *F = SM.getFileEntryForID(SM.getFileID(Loc));
+  if (!F)
+    return None;
+  auto FilePath = getCanonicalPath(F, SM);
+  if (!FilePath) {
+    log("failed to get path!");
+    return None;
+  }
+  Location L;
+  L.uri = URIForFile::canonicalize(*FilePath, TUPath);
+  // We call MeasureTokenLength here as TokenBuffer doesn't store spelled tokens
+  // outside the main file.
+  auto TokLen = Lexer::MeasureTokenLength(Loc, SM, AST.getLangOpts());
+  L.range = halfOpenToRange(
+      SM, CharSourceRange::getCharRange(Loc, Loc.getLocWithOffset(TokLen)));
+  return L;
+}
+
 } // namespace clangd
 } // namespace clang

clang-tools-extra/clangd/XRefs.cpp

getDeclAtPosition(ParsedAST &AST, SourceLocation Pos, DeclRelationSet Relations,
                   ASTNodeKind *NodeKind = nullptr) {
   std::vector<const NamedDecl *> Result;
   for (auto &Entry :
        getDeclAtPositionWithRelations(AST, Pos, Relations, NodeKind))
     Result.push_back(Entry.first);
   return Result;
 }
 
-// Expects Loc to be a SpellingLocation, will bail out otherwise as it can't
-// figure out a filename.
-llvm::Optional<Location> makeLocation(const ASTContext &AST, SourceLocation Loc,
-                                      llvm::StringRef TUPath) {
-  const auto &SM = AST.getSourceManager();
-  const FileEntry *F = SM.getFileEntryForID(SM.getFileID(Loc));
-  if (!F)
-    return None;
-  auto FilePath = getCanonicalPath(F, SM);
-  if (!FilePath) {
-    log("failed to get path!");
-    return None;
-  }
-  Location L;
-  L.uri = URIForFile::canonicalize(*FilePath, TUPath);
-  // We call MeasureTokenLength here as TokenBuffer doesn't store spelled tokens
-  // outside the main file.
-  auto TokLen = Lexer::MeasureTokenLength(Loc, SM, AST.getLangOpts());
-  L.range = halfOpenToRange(
-      SM, CharSourceRange::getCharRange(Loc, Loc.getLocWithOffset(TokLen)));
-  return L;
-}
-
 // Treat #included files as symbols, to enable go-to-definition on them.
 llvm::Optional<LocatedSymbol> locateFileReferent(const Position &Pos,
                                                  ParsedAST &AST,
                                                  llvm::StringRef MainFilePath) {
   for (auto &Inc : AST.getIncludeStructure().MainFileIncludes) {
     if (!Inc.Resolved.empty() && Inc.HashLine == Pos.line) {
       LocatedSymbol File;
       File.Name = std::string(llvm::sys::path::filename(Inc.Resolved));

clang-tools-extra/clangd/unittests/HoverTests.cpp

TEST(Hover, DocsFromAST) {
   auto AST = TU.build();
   for (const auto &P : T.points()) {
     auto H = getHover(AST, P, format::getLLVMStyle(), nullptr);
     ASSERT_TRUE(H);
     EXPECT_EQ(H->Documentation, "doc");
   }
 }
 
+TEST(Hover, DocLocation) {
+  const std::string Filename = "main.cpp";
+  const std::string HeaderFilename = "header.h";
+
+  struct {
+    const char *const Code;
+    const std::function<void(HoverInfo &)> ExpectedBuilder;
+  } Cases[] = {
+      {
+          R"cpp(
+      // main-doc
+      void main_file_fun();
+
+      void foo() { m^ain_file_fun(); }
+      )cpp",
+          [&](HoverInfo &HI) {
+            HI.Documentation = "main-doc";
+            HI.DocumentationLocation.range.start.line = 1;
+            HI.DocumentationLocation.range.start.character = 6;
+            HI.DocumentationLocation.range.end.line = 1;
+            HI.DocumentationLocation.range.end.character = 17;
+            HI.DocumentationLocation.uri =
+                URIForFile::canonicalize(testPath(Filename), Filename);
+          }},
+      {
+          R"cpp(
+      void foo() { hea^der_fun(); }
+      )cpp",
+          [&](HoverInfo &HI) {
+            HI.Documentation = "main-doc";
+            HI.DocumentationLocation.range.start.line = 1;
+            HI.DocumentationLocation.range.start.character = 2;
+            HI.DocumentationLocation.range.end.line = 1;
+            HI.DocumentationLocation.range.end.character = 8;
+            HI.DocumentationLocation.uri = URIForFile::canonicalize(
+                testPath(HeaderFilename), HeaderFilename);
+          }},
+  };
+
+  const std::string Header = R"cpp(
+  // doc
+  void header_fun();
+  )cpp";
+
+  for (const auto &Case : Cases) {
+    SCOPED_TRACE(Case.Code);
+
+    Annotations T(Case.Code);
+    TestTU TU = TestTU::withCode(T.code());
+    TU.HeaderCode = Header;
+    TU.Filename = Filename;
+    TU.HeaderFilename = HeaderFilename;
+
+    auto Index = std::make_unique<FileIndex>();
+    TU.preamble([&](ASTContext &Ctx, std::shared_ptr<Preprocessor> PP,
+                    const CanonicalIncludes &CanonIncludes) {
+      Index->updatePreamble(TU.Filename, "null", Ctx, PP, CanonIncludes);
+    });
+
+    auto AST = TU.build();
+    auto H = getHover(AST, T.point(), format::getLLVMStyle(), Index.get());
+    ASSERT_TRUE(H);
+
+    HoverInfo Expected;
+    Case.ExpectedBuilder(Expected);
+
+    EXPECT_EQ(H->Documentation, Expected.Documentation);
+    EXPECT_EQ(H->DocumentationLocation, Expected.DocumentationLocation);
+  }
+}
+
 TEST(Hover, NoCrash) {
   Annotations T(R"cpp(
     /* error-ok */
     template<typename T> T foo(T);
 
     // Setter variable heuristic might fail if the callexpr is broken.
     struct X { int Y; void [[^setY]](float) { Y = foo(undefined); } };)cpp");