Alternative highlighting for Rust code block in rustdoc · Issue #78917 · rust-lang/rust (original) (raw)

Context https://twitter.com/imperioworld_/status/1325916530257833984 cc @GuillaumeGomez

Description

I'm the author of https://github.com/Hywan/inline-c-rs/. It allows to write C code inside Rust. It's a super basic proc_macro that transforms the code into a string (with some extra manipulations), which is saved inside a temp file that is compiled by a C/C++ compiler, and finally run. That's useful for testing C API of a Rust program inside Rust with the Rust tooling (like cargo test). It is super useful for us at https://github.com/wasmerio/wasmer.

Recently, we pushed the concept further: Using inline-c-rs inside documentation, like this:

/// Blah blah blah. /// /// # Examples /// /// rust /// # use inline_c::assert_c; /// # fn main() { /// # (assert_c! { /// # #include "tests/wasmer_wasm.h" /// # /// int main() { /// wasm_engine_t* engine = wasm_engine_new(); /// wasm_store_t* store = wasm_store_new(engine); /// /// // etc. /// /// return 0; /// } /// # }) /// # .success(); /// # } /// #[no_mangle] pub unsafe extern "C" fn wasm_module_new(/* skipped /) -> / skipped */ { // skipped }

This documentation is:

• ✅ written in Rust, and contains C,
• ✅ is tested by cargo test --doc because the code block is tagged with ```rust … so we can test C with cargo test 🤪!
• ✅ is compiled to HTML by rustdoc.

The result of cargo doc looks like this:

That's excellent! All the “Rust decoration” is “removed” (thanks to # …), and only the C code stays. That's insane I know, but it works and that's super fun.

One problem though:

• ❌ The highlighting is incorrect.

Because it's a ```rust code block, there is a special handler for that I assume. I tried to write rust,language-c but the `language-c` part is ignored and is not present in the generated HTML code, as it can be seen here:

## Expectation

I would expect ```` ```rust ```` to be a special keyword that unfolds to `rust` \+ \`language-rust\`:

* The former describes that it's a Rust code block, and consequently is a candidate for a test,
* The second describes the syntax highlighting ruleset to apply for the HTML documentation.

This keyword could have a different meaning in the presence of `language-` which “cancels” `language-rust`.

In other words, writing `rust,language-c` would keep the actual behavior of `rust` but it will disable the default highlighting to allow the user to define another one.

How does it sound?

## Motivation

The technique used by `inline-c-rs` can be ported to other languages. It's just super fun to see C code inside Rust documentation that is also tested by `cargo doc`. I'm sure this technique can be used by other languages in the future.