Compiling rust code in comments

help
1

Are there specific rules to use to have rust code in /// comments being compiled by cargo test?

I have an exemple where the code is placed in

/// ```rust 
/// /* some struct definition */ 
/// fn main() {
/// /* some code */ 
/// }
/// ```

doesn't compile. But if I copy the very same code (& remove the leading '/// ') into an example I place in the crates' examples folder it compiles & run just fine

2

If by doesn't compile you mean that the code is not compiled at all, it might be a missing blank line.

Compare this, where the code will be completely ignored

//! Bla bla bla
//! ```rust
//! fn main() {
//! }
//! ```

to this, which compiles

//! Bla bla bla
//!
//! ```rust
//! fn main() {
//! }
//! ```

Notice the blank line before the backtics.

Hope this helps!

3

No it is compiled but I have error messages that I don't have when compiling (and running) the example separately.

I'm using a procedural macro (if it changes something) and the error I have is about missing crates that the generated code uses

4

Could you give a more specific example? And the error message?

5

The comments that I am trying to add: https://github.com/bgbahoue/he-di/blob/master/he_di/src/container/map_container.rs > line 37 and below (currently disabled)

The same test as a separate example > https://github.com/bgbahoue/he-di/blob/master/he_di/examples/map_container_doc_example.rs

When I'm removing the ignore tag I have the following error when running cargo test

---- src/container/map_container.rs - container::map_container::Container (line 37) stdout ----
        error[E0433]: failed to resolve. Use of undeclared type or module `__DI_FooImpl_Foo_he_di`
 --> <anon>:9:10
  |
9 | #[derive(Component)]
  |          ^^^^^^^^^ Use of undeclared type or module `__DI_FooImpl_Foo_he_di`

error[E0433]: failed to resolve. Use of undeclared type or module `__DI_FooImpl_Foo_he_di`
 --> <anon>:9:10
  |
9 | #[derive(Component)]
  |          ^^^^^^^^^ Use of undeclared type or module `__DI_FooImpl_Foo_he_di`

error[E0433]: failed to resolve. Use of undeclared type or module `__DI_FooImpl_Foo_he_di`
 --> <anon>:9:10
  |
9 | #[derive(Component)]
  |          ^^^^^^^^^ Use of undeclared type or module `__DI_FooImpl_Foo_he_di`

error[E0433]: failed to resolve. Use of undeclared type or module `__DI_FooImpl_Foo_he_di`
 --> <anon>:9:10
  |
9 | #[derive(Component)]
  |          ^^^^^^^^^ Use of undeclared type or module `__DI_FooImpl_Foo_he_di`

error[E0433]: failed to resolve. Use of undeclared type or module `__DI_FooImpl_Foo_he_di`
 --> <anon>:9:10
  |
9 | #[derive(Component)]
  |          ^^^^^^^^^ Use of undeclared type or module `__DI_FooImpl_Foo_he_di`

error[E0433]: failed to resolve. Use of undeclared type or module `__DI_FooImpl_Foo_he_di`
 --> <anon>:9:10
  |
9 | #[derive(Component)]
  |          ^^^^^^^^^ Use of undeclared type or module `__DI_FooImpl_Foo_he_di`

error[E0433]: failed to resolve. Use of undeclared type or module `__DI_FooImpl_Foo_anymap`
 --> <anon>:9:10
  |
9 | #[derive(Component)]
  |          ^^^^^^^^^ Use of undeclared type or module `__DI_FooImpl_Foo_anymap`

error[E0433]: failed to resolve. Use of undeclared type or module `__DI_FooImpl_Foo_anymap`
 --> <anon>:9:10
  |
9 | #[derive(Component)]
  |          ^^^^^^^^^ Use of undeclared type or module `__DI_FooImpl_Foo_anymap`

error[E0433]: failed to resolve. Use of undeclared type or module `__DI_FooImpl_Foo_he_di`
 --> <anon>:9:10
  |
9 | #[derive(Component)]
  |          ^^^^^^^^^ Use of undeclared type or module `__DI_FooImpl_Foo_he_di`

error[E0433]: failed to resolve. Use of undeclared type or module `__DI_FooImpl_Foo_anymap`
 --> <anon>:9:10
  |
9 | #[derive(Component)]
  |          ^^^^^^^^^ Use of undeclared type or module `__DI_FooImpl_Foo_anymap`

error: cannot continue compilation due to previous error

thread 'rustc' panicked at 'Box<Any>', src/librustc/session/mod.rs:218
note: Run with `RUST_BACKTRACE=1` for a backtrace.
thread 'rustc' panicked at 'couldn't compile the test', src/librustdoc/test.rs:278
6

If you ignore the code example in src/container/container_builder.rs, line 110, this test work. My best guess at this point is that some global state in your procedural macro is preserved between the compilations of the various code in /// comments.

This shared state is likely to be IMPORT_MAP_SINGLETON in he_di_derive/src/component.rs. Because the two examples use the same component_name and interface, your procedural macros believe it has already generated the imports and doesn't generate them again. If you rename one the FooImpl in one of the two code examples, the tests pass.

If I'm not mistaken, rustdoc load the plugin (he_di_derive in this case) once at the start.This mean that global variable are not reinitialized between the compilation of the various examples. I'm not sure if this should be considered a bug in rustdoc or not. You may want to create an issue on github to be sure.

In case you missed it, some of the way the code examples are transformed is documented in the book.

7

Thanks a lot for your reply. I was able to work around the issue renaming the Foo class. I'm not sure either if this should be considered a bug or not indeed (sure feels weird though, even if quite specific ...)