rust-lang / rust.vim

Vim configuration for Rust.
Apache License 2.0
3.89k stars 295 forks source link

Should add a toggle for highlighting of code inside doc comments #248

Open mandeep opened 6 years ago

mandeep commented 6 years ago

rust-vim version: master branch

I recently updated rust.vim to the master branch and noticed that examples in doc comments are no longer considered doc comments. Take the following example:

/// Bresenham's algorithm: Draw a line in the given color from (x0, y0) to (x1, y1)
///
/// # Examples
///
/// ```
/// let mut buffer = image::ImageBuffer::new(1921, 1081);
///
/// draw_line(0, 0, 1920, 1080, &mut buffer, image::Rgb([255, 255, 255]))
/// ```
///

The lines between the first ``` and last ``` are not highlighted as doc comments. Instead they are shown as normal rust code.

chris-morgan commented 6 years ago

This is deliberate: see #63. Such regions in doc comments will be treated by the compiler as tests and thus interpreted as code, so it makes sense to highlight it thus.

By the looks of it, we didn’t implement a switch to disable this; we should probably add such a thing—might hijack this issue to track that instead.

I do wish Vim supported nested highlighting (as distinct from nested matching which it definitely has) so that you had the option of an in-between highlighting, but it doesn’t.

mandeep commented 6 years ago

Thanks for the quick response. I think a switch would be appropriate.

One thing to remember is that cargo will only treat examples as tests if the examples are written in a library. If the project is created as --bin, the examples are not run as tests. In my case, I'm working on a binary but I include examples for documentation purposes only.