[PATCH] D45999: [clangd] Retrieve minimally formatted comment text in completion.

[Ilya Biryukov via Phabricator via cfe-commits]

ilya-biryukov added inline comments.


================
Comment at: clangd/CodeCompletionStrings.h:24
 
+/// Gets a raw documentation comment of \p Result.
+/// Returns empty string when no comment is available.
----------------
sammccall wrote:
> What does raw mean - range of the file? indentation stripped?
Added more details and a reference to `RawComment::getFormattedString`, which is used to get the comment text and has a more descriptive doc.


================
Comment at: clangd/CodeCompletionStrings.h:29
+
+/// Gets a raw documentation comment of the current active parameter
+/// of \p Result.
----------------
sammccall wrote:
> sammccall wrote:
> > "active" is a bit confusing - at this level we just care which arg you're interested in, right?
> Is this typically a substring of getDocComment for the function? If so, noting that would make this clearer.
This refers to the parameter that should be reported as active in `signatureHelp`.
Agree that it requires too much context to understand, changed to a more detailed description involving `CurrentArg` parameter.




================
Comment at: clangd/CodeCompletionStrings.h:29
+
+/// Gets a raw documentation comment of the current active parameter
+/// of \p Result.
----------------
ilya-biryukov wrote:
> sammccall wrote:
> > sammccall wrote:
> > > "active" is a bit confusing - at this level we just care which arg you're interested in, right?
> > Is this typically a substring of getDocComment for the function? If so, noting that would make this clearer.
> This refers to the parameter that should be reported as active in `signatureHelp`.
> Agree that it requires too much context to understand, changed to a more detailed description involving `CurrentArg` parameter.
> 
> 
> Is this typically a substring of getDocComment for the function? If so, noting that would make this clearer.
I mechanically translated the original source code without looking too much on what it does :-)

Extracting a substring from the function doc would be the behavior I expect.
However, we simply try to get doc comment for parameter in the same way we do for functions (e.g. look for comment doc for parameter decl, without looking at function decl in the first place)
It means we'll always get the empty doc currently. At least, I couldn't make the current code produce any docs for the parameter.

I would still keep this function, as it seems to be called in the right places. But we definitely need to parse a function comment instead.


================
Comment at: clangd/CodeCompletionStrings.h:49
+/// getDocComment functions declared above.
+std::string getDocumentation(const CodeCompletionString &CCS,
+                             llvm::StringRef DocComment);
----------------
sammccall wrote:
> The name here is confusingly similar to getDocComment, and the comment doesn't really explain how they're different.
> 
> Consider calling this formatDocumentation, with a comment like "Assembles formatted documentation for a completion result. This includes documentation comments and other relevant information like annotations."
Thanks! That was definitely confusing.


Repository:
  rCTE Clang Tools Extra

https://reviews.llvm.org/D45999