[clangd] Use doxygen \param tag when hovering parameter and for CalleeArgInfo

clang-tools-extra/clangd/CodeCompletionStrings.cpp

SymbolDocumentationOwned getDeclDocumentation(const ASTContext &Ctx,
                                               const NamedDecl &Decl) {
   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 {};
   }
+  // For parameters, check if they are documented in their function declaration
+  if (isa<ParmVarDecl>(Decl))
+    if (const auto *FD = dyn_cast<FunctionDecl>(Decl.getDeclContext())) {
+      auto ParamDoc = getDeclDocumentation(Ctx, *FD).getParamDoc(Decl.getName());
+      if (!ParamDoc.empty())
+        return SymbolDocumentationOwned::descriptionOnly(std::move(ParamDoc));
+    }
+
   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()));
 
   SymbolDocumentationOwned Doc = parseDoxygenComment(*RC, Ctx, &Decl);

clang-tools-extra/clangd/Hover.h

struct PassType {
     PassMode PassBy = Ref;
     // True if type conversion happened. This includes calls to implicit
     // constructor, as well as built-in type conversions. Casting to base class
     // is not considered conversion.
     bool Converted = false;
   };
   // Set only if CalleeArgInfo is set.
   llvm::Optional<PassType> CallPassType;
+  // Documentation of the parameter that this symbol is passed as.
+  // Set only if CalleeArgInfo is set.
+  llvm::Optional<std::string> CallArgDocs;
 
   /// Produce a user-readable information.
   markup::Document present() const;
 };
 
 inline bool operator==(const HoverInfo::PrintedType &LHS,
                        const HoverInfo::PrintedType &RHS) {
   return std::tie(LHS.Type, LHS.AKA) == std::tie(RHS.Type, RHS.AKA);

clang-tools-extra/clangd/Hover.cpp

if (const auto *FD = llvm::dyn_cast<FieldDecl>(&ND)) {
     }
     return;
   }
 }
 
 // If N is passed as argument to a function, fill HI.CalleeArgInfo with
 // information about that argument.
 void maybeAddCalleeArgInfo(const SelectionTree::Node *N, HoverInfo &HI,
-                           const PrintingPolicy &PP) {
+                           const PrintingPolicy &PP, const ASTContext &Ctx) {
   const auto &OuterNode = N->outerImplicit();
   if (!OuterNode.Parent)
     return;
   const auto *CE = OuterNode.Parent->ASTNode.get<CallExpr>();
   if (!CE)
     return;
   const FunctionDecl *FD = CE->getDirectCallee();
   // For non-function-call-like operatators (e.g. operator+, operator<<) it's
   // not immediattely obvious what the "passed as" would refer to and, given
   // fixed function signature, the value would be very low anyway, so we choose
   // to not support that.
   // Both variadic functions and operator() (especially relevant for lambdas)
   // should be supported in the future.
   if (!FD || FD->isOverloadedOperator() || FD->isVariadic())
     return;
 
   // Find argument index for N.
   for (unsigned I = 0; I < CE->getNumArgs() && I < FD->getNumParams(); ++I) {
     if (CE->getArg(I) != OuterNode.ASTNode.get<Expr>())
       continue;
 
     // Extract matching argument from function declaration.
-    if (const ParmVarDecl *PVD = FD->getParamDecl(I))
+    if (const ParmVarDecl *PVD = FD->getParamDecl(I)) {
       HI.CalleeArgInfo.emplace(toHoverInfoParam(PVD, PP));
+
+      SymbolDocumentationOwned ParamDoc = getDeclDocumentation(Ctx, *PVD);
+      if (!ParamDoc.empty())
+        HI.CallArgDocs.emplace(ParamDoc.Description);
+    }
     break;
   }
   if (!HI.CalleeArgInfo)
     return;
 
   // If we found a matching argument, also figure out if it's a
   // [const-]reference. For this we need to walk up the AST from the arg itself
   // to CallExpr and check all implicit casts, constructor calls, etc.
if (const SelectionTree::Node *N = ST.commonAncestor()) {
       if (const auto *DeclToUse = pickDeclToUse(Decls)) {
         HI = getHoverContents(DeclToUse, PP, Index, TB);
         // Layout info only shown when hovering on the field/class itself.
         if (DeclToUse == N->ASTNode.get<Decl>())
           addLayoutInfo(*DeclToUse, *HI);
         // Look for a close enclosing expression to show the value of.
         if (!HI->Value)
           HI->Value = printExprValue(N, AST.getASTContext());
-        maybeAddCalleeArgInfo(N, *HI, PP);
+        maybeAddCalleeArgInfo(N, *HI, PP, AST.getASTContext());
       } else if (const Expr *E = N->ASTNode.get<Expr>()) {
         HI = getHoverContents(E, AST, PP, Index);
       } else if (const Attr *A = N->ASTNode.get<Attr>()) {
         HI = getHoverContents(A, AST);
       }
       // FIXME: support hovers for other nodes?
       //  - built-in types
     }
if (CallPassType->PassBy != HoverInfo::PassType::Value) {
       if (CallPassType->PassBy == HoverInfo::PassType::ConstRef)
         OS << "const ";
       OS << "reference ";
     }
     if (CalleeArgInfo->Name)
       OS << "as " << CalleeArgInfo->Name;
     if (CallPassType->Converted && CalleeArgInfo->Type)
       OS << " (converted to " << CalleeArgInfo->Type->Type << ")";
+    if (CallArgDocs)
+      OS << ": " << *CallArgDocs;
     Output.addParagraph().appendText(OS.str());
   }
 
   if (!Documentation.Description.empty())
     parseDocumentation(Documentation.Description, Output);
 
   if (!Documentation.Warnings.empty()) {
     Output.addRuler();

clang-tools-extra/clangd/SymbolDocumentation.h

public:
   /// Constructs with all fields as empty strings/vectors.
   SymbolDocumentation() = default;
 
   SymbolDocumentation<llvm::StringRef> toRef() const;
   SymbolDocumentation<std::string> toOwned() const;
 
   bool empty() const { return CommentText.empty(); }
 
+  /// @return The documentation of the parameter with the given \p Name, or
+  /// an empty string if there's no documentation for this parameter
+  String getParamDoc(llvm::StringRef Name) {
+    auto *Doc = llvm::find_if(
+        Parameters, [&Name](const ParameterDocumentation<String> &ParamDoc) {
+          return ParamDoc.Name == Name;
+        });
+    return Doc != Parameters.end() ? Doc->Description : "";
+  }
+
   /// Paragraph of the "brief" command.
   String Brief;
 
   /// Paragraph of the "return" command.
   String Returns;
 
   /// Paragraph(s) of the "note" command(s)
   llvm::SmallVector<String, 1> Notes;