Are the comments about using # in rustdoc outdated?

1

Reading Redirecting..., it says:

Consider an example block that looks like this:

/// Some documentation.
# fn foo() {}

It will render like this:

/// Some documentation.

Yes, that's right: you can add lines that start with #, and they will be hidden from the output, but will be used when compiling your code.

Well, that doesn't seem to work:

    /// Test some documentation
    # fn foo() {}

$ cargo test
   Compiling diamond-drops-node v0.1.0-a (file:///home/james/dod/node)
error: expected `[`, found `fn`
   --> node/src/modules/collation/blob.rs:178:7
    |
178 |     # fn foo() {}
    |       ^^ expected `[`

rustc 1.27.0-nightly (79252ff4e 2018-04-29)

2

Just to be sure you're writting it all in the documentation itself right ?

/// Doc text here ...
///
/// # Examples
///
/// ```
/// /// some documentation
/// # fn foo() {} // not shown
/// assert!(true);
/// ```
2 Likes
3

Ah, no I wasn't, that wasn't clear to me, perhaps that should be clarified!

4

Yup, that seems good. Would you mind filing a bug, please? http://github.com/rust-lang/rust/issues/new

1 Like
5

https://github.com/rust-lang/rust/issues/50816

1 Like