Documentation doesn't show up in certain cases

[DianaNites]

If documentation for an item is separated by newlines, rust-analyzer doesn't recognize it.

This will show "Example" on hover

/// Example
fn test() {}

but this will not.

/// Example

fn test() {}

Ran into this because CString has this problem. Removing the newline immediately works around the issue, but editing the source isn't ideal or persistent.

Environment

rust-analyzer commit 1c2d413
VSCode 1.43.2

[edwin0cheng]

I think there is a bug in parser, here is the SyntaxTree of code mentioned (By Show Syntax Tree Command):

COMMENT@[15; 30) "/// Example Doc"   <-- The comment is outside FN_DEF
  WHITESPACE@[30; 32) "\n\n"
  FN_DEF@[32; 44)
    FN_KW@[32; 34) "fn"
    WHITESPACE@[34; 35) " "
...

[matklad]

I think this should be fixed over here:

https://github.com/rust-analyzer/rust-analyzer/blob/78a2678b6d31eb8a0c5eafd0fdf4eea7da5321a3/crates/ra_syntax/src/parsing/text_tree_sink.rs#L144-L169

Here, we should keep the logic about \n\n for non-doc comments, but, if there's a doc comment after a blank line, we should attach it nevetheless.

That is, we (roughly) should look at the next token after \n\n and, if it is an outer doc comment, we should not break the loop.

[ltentrup]

I would like to give it a try. However, I noticed that this change also changes the syntax tree of

https://github.com/rust-analyzer/rust-analyzer/blob/6f0d8db529478ce41b429f06708fa600a97c2151/crates/ra_syntax/test_data/parser/ok/0035_weird_exprs.rs#L16-L18

although this has nothing to do with doc-comments. Is this the wanted behavior? There seems to be no difference between doc-comments and regular comments in the parser.

[matklad]

No, non-doc comments should not be attached, and that file is actually a great example, as comment refers to the whole set of items, and not just to a function. We probably should add a dedicated test for attachment behavior though (just add a new file to test_data/parser/ok).

The n_attached_trivias receives the text of the tokens, so you can distinguish between doc and non-doc comment by looking at the prefix.

[ltentrup]

Thanks for the clarification! I have opened a pull-request that implements those changes