Clickable links in markdown don't do anything

[kjeremy]

I noticed that hovering over std::io::stdin() produces a nice documentation comment including a link to the documentation for another function. Clicking on that link doesn't seem to do anything. I'm not sure if this is something we need to handle in the extension or the LSP but we should handle it if we can.

[DJMcNab]

Links in markdown in hovers in vscode have never worked well for me - e.g in typescript.

However, we should try to handle this in the language server layer, rewriting the rustdoc style urls into file style urls (or even linking to the equivalent page in cargo doc).

[kjeremy]

This might be related to microsoft/vscode#40397

[kjeremy]

We may be able to get around this issue by adding a markdown plugin https://code.visualstudio.com/api/extension-guides/markdown-extension

[numfin]

@kjeremy hi idk where to ask, but what is the progress of this issue?

[kjeremy]

There hasn't been. PRs welcome :)

[kjeremy]

An alternative (don't think it would work with hover though) could be to implement https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_documentLink

[zacps]

I might take a look at this (no promises on progress). The way I'd like it to work is to have a few options:

• Open documentation in a panel (Markdown rendered)
• Open documentation in browser (Local file URLs)
• Open documentation in browser (docs.rs)

I haven't done any VS Code extension development before so this might take me a little while.

[kjeremy]

@zacps

So off the top of my head I THINK the best way to implement this is using https://microsoft.github.io/language-server-protocol/specifications/specification-3-15/#textDocument_documentLink then it will work for all clients that support this feature.

To get vscode to start using this capability you would need to turn it on here (don't worry about the resolve provider for now, we can add that later): https://github.com/rust-analyzer/rust-analyzer/blob/1bc1f28bc58b2dbcf8f8f548c277e2c90e3075cd/crates/rust-analyzer/src/caps.rs#L76

and install the appropriate handler somewhere around here: https://github.com/rust-analyzer/rust-analyzer/blob/1bc1f28bc58b2dbcf8f8f548c277e2c90e3075cd/crates/rust-analyzer/src/main_loop.rs#L523

and then define your function in handlers.rs.

I think what you could do is scan all doc comments in the document for rustdoc links and convert them to a list of DocumentUri / Range for the reply. That would at least get us all local links.

After that we could make it configurable for docs.rs (or even a fallback?). Those would probably take advantage of the resolve request.

[zacps]

I'm not sure the document link provider does the right thing. If I understand correctly it's concerned with identifying and resolving links inline within a document, i.e. hyperlinks in markdown.

What I want to add:

• This issue: the ability to click links in hover previews (This should just require rewriting them in the hover provider). Opening these in a panel might be harder than in the browser.
• The ability to document a symbol under the cursor. As far as I can tell this will need to be a protocol extension.

As far as the logic on the lsp side there's two main parts:

• Resolve a symbol (under cursor, from link) the former is already implemented. The later should be simple enough if it isn't already implemented.
• Render documentation. There's the existing documentation renderer for hovers which doesn't provide as much information as rustdoc but is in a nicer format. It'd be great if rustdoc could generate documentation for a single item on demand and/or generate markdown/rst docs.

[kjeremy]

You are correct. These are separate issues but we should be consistent.

If you are massaging the returned markdown links we should also make sure that it works for the docs returned by signature help/completion etc.

[zacps]

So far I've found comrak a markdown parser which supports editing the ast and rendering as markdown.

For now I'm editing ra_syntax/src/ast/traits.rs::DocCommentsOwner::doc_comment_text.

The links in markdown are relative to the current symbol, so I'm trying to get the qualified name of the AstNode.

I've found that you can get the Name of an AstNode with support::child(self.syntax()). Is there an easy way to get the path to the symbol other than traversing the ancestors looking for nodes with names?

[flodiebold]

This needs to happen on a higher level than ra_syntax, because you can't resolve names from there, and doc_comments_text shouldn't be doing any complicated/semantic processing anyway. I would probably suggest implementing it somewhere in ra_ide, where it will be used, for now. Then you should be able to use the Semantics API to turn the AST node into a definition, resolve paths etc.

[zacps]

Thanks for the API tip. It definitely wasn't intended as a permanent location, don't worry about that. Just wanted to find somewhere I could poke at it and get results.

[zacps]

I'm now at the stage of actually implementing the resolution logic, unfortunately it seems to be somewhat complicated.

I think I can approximate logic which should work for most cases, but it would be nice to be able to reuse the work in librustdoc. From a brief look it seems like that might be more trouble than it's worth however.

---

Edit: Current specific problem is figuring out where rustdoc generated documentation for re-exported items. For example if a module is private and its item is re-exported elsewhere the semantics API won't give the 'correct' module path, and we can't resolve relative references.

I'm not sure if there's anything in rust-analyzer that has to deal with this yet.

See https://doc.rust-lang.org/rustdoc/the-doc-attribute.html#docno_inlinedocinline

[zacps]

I now have a prototype capable of rewriting path-based links. It'll require a bit of tidying up and I still have to write the intra-doc-link resolution.

I'll probably put a draft PR up soon.