lsp_doc

What

This crate provides an attribute macro to embed any plain-text file (interpreted as markdown) into the Rust documentation for the LSP hover/preview for any editor.

This is a simplified version of the lsp_doc macro from https://github.com/MasterTemple/lsp_doc/ that works with stable Rust.

Using this version the generated #[doc] attribute will always be placed before all other attributes, so it will be shown first in the hover/preview.

Why?

Currently you can say either of the following:

/// [](some_file.md)
fn some_func() {}

// or

#[doc = include_str!("../another_file.md")]
fn another_func() {}

However, while these work with cargo doc, neither of these show up in the LSP hover/preview.

See https://github.com/rust-lang/rust-analyzer/issues/11137

This macro resolves that.

Screenshots

Given

*.rs

#[lsp_doc("lorem.md")]
#[lsp_doc("table.md")]
fn anything() {}

lorem.md

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

table.md

| Header 1 | Header 2 |
| -------- | -------- |
| Value 1  | Value 2  |
| Value 3  | Value 4  |

VSCode

Neovim

Note

• Paths are relative to the crate root directory
• Multiple embeds for the same item are supported but may not be displayed in the order they are written
• Images are not currently supported
• File contents are cached by rust-analyzer, so if you frequently edit the embedded file, you might not see immediate updates