I would love to help If possible, can you please guide me @stamblerre

@Tolsee: absolutely! The main feature here involves generating documentation from a types.Object. You can see that in both completion and hover, we have access to a types.Object, a file's AST, a types.Package, and a types.Info. The package https://godoc.org/go/doc will likely be needed here as well. The tool https://github.com/zmb3/gogetdoc also does this task, so it might be helpful to look at.

Feel free to send me a change for review if you'd like to work on this.

Note: If in case getting the docs takes a little more time, then it need not be sent for each of the completion item in the result. There is a resolve completion item request for just the completion item in focus. You can send the docs as part of this request.

Also happy to assist @Tolsee, let me know if I can be of any help.

Saw in the tools update that this would be a good issue to get started. Is anybody actively working on this? If not I'm game to give it a go, probably starting in trying to get any docs included in Hover as that seems like a fairly clear start.

Don't believe so - just assign yourself when you start working so others will be aware. Feel free to reach out to me here or on Slack with any questions! We should be able to add a documentation function that can be used by both Hover and Completion.

Great, let me see if I can get a dev environment rolling against VSCode and if that works then I'll volunteer for this. I've done some documentation extraction for our own go stuff so have some experience on this so in theory should be able to knock this out.

Ok, I'm going to give this a go, got this working with a vscode-ception of gopls which is fun. I can't assign myself this but I'll look at this over the next few days and hopefully have something in a day or two to show.

Looks like I can't assign it to you either - I guess you have to have some ownership in the repository or something. Self-assigned to make it obvious that this is taken.

Realize this is a slightly different issue but on the call you mentioned not liking the tag treatment when looking at a struct. Started looking at that since that seemed an even simpler entry point and that looks like explicit behavior in writeType. How do you want those tags represented? Do you want them gone entirely? (I feel that is likely most natural, I don't expect tags to be included in a hover, but checking what desired is)

good idea! yeah i think eliminating them makes the most sense.

Ah, I see now, the format is part of the core library in ObjectString... So next question is do we want to mangle what we get back from ObjectString or reimplement/copy and tweak that implementation into lsp? Seems the latter is the only reasonable option.

I looked at this when writing the guru compatibility, I think a complete implementation inside lsp/source is the only viable approach.
I was thinking of writing something that builds a cleaned ast and then using the normal printer to build the string, but I did not look hard enough to be sure that is the right approach.

I'm not convinced it's the tags that makes the tooltip hard to look at, but rather the lack of formatting.

We've been displaying the tags in Atom's hover implementation for a while and haven't received any feedback that the tags are a problem. Here's a screenshot of a tooltip that includes tags but properly formats the struct type definition:

Ya, I kinda agree. Maybe we should start with formatting first and see how people feel about it before reimplementing all the ObjectString stuff? Is that a vscode responsibility or the responsibility of the markdown we produce?

I'd like to jump on this one if it is back to available.

I actually have a CL in progress to fix this, sorry I didn't write here earlier. It's actually a fairly big change, so I may be able to file several more issues once my first one is in.

Change https://golang.org/cl/172661 mentions this issue: internal/lsp: use ast.Nodes for hover information

Change https://golang.org/cl/172958 mentions this issue: internal/lsp: support comments on hover for all typenames, funcs

As I'm sure you are aware, note that Go doc strings are not Markdown but rather have their own minimalistic formatting. For them to display with formatting correctly they will need to be converted to Markdown before returning them if we want them to show up formatted in the editor correctly. See microsoft/vscode-go#2245 where I implemented this transformation albeit in JS and here it is needed in Go.

Thanks for bringing this to my attention, @segevfiner! Right now in gopls we don't do anything to make sure the comments are formatted well, so I will definitely look into this.

Change https://golang.org/cl/180657 mentions this issue: internal/lsp: attach documentation to signature help

The last case that needs documentation is completion items. This should probably be done on completionItem/resolve to avoid extra work.

To do that on completionItem/resolve we first need to add some info to the returned CompletionItem-s data field that can be used to quickly get back the types.Object for the given item. Once we have that resolve can use that to get the item again and extract the relevant documentation for it. It also seems that the existing code for documentation is based on ast instead of types, so we either need code to grab documentation from types or get the ast node in resolve instead.

So what should that key for looking up the object in resolve be?

I do think we should cache identifier information to avoid recomputing hover information, but I think to start, we may be able to avoid caching. If we know the position of the completion item, we can get the identifier at the position and get the documentation that way. It might not be technically correct, as the code could change before the item is resolved, but in practice, I'd be surprised if that were a common occurrence.

I think gopls has type info cached so it sounds reasonable to me it will already have a mechanism for this. Maybe Info.ObjectOf but I didn't try this yet.

Change https://golang.org/cl/184721 mentions this issue: internal/lsp: add documentation to completion items

The above change experimentally added the documentation to the completion items, but we still have a few things to determine before turning this feature on by default. In particular - should we move to the approach of using completionItem/resolve or stick to population documentation for all items in textDocument/completion? This will require benchmarks to compare the approaches.

Completion documentation was turned on by default at master, so closing this issue.