Using Markdown in documentation

help
1

I understand one can use Markdown syntax in comments intended for documentation. However, in the following snip, the intended H3 header does not show up in the HTML.

/// ### Auxiliary functions

///	Function to convert character to digit
fn char_to_digit(c: char) -> u8 {
	(c as u8) - C0
}
2

Use clippy :wink:

warning: empty line after doc comment
 --> src/lib.rs:1:1
  |
1 | / /// ### Auxiliary functions
2 | |
  | |_^
3 |   ///    Function to convert character to digit
4 |   fn char_to_digit(c: char) -> u8 {
  |   ---------------- the comment documents this function
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/rust-1.93.0/index.html#empty_line_after_doc_comments
  = note: `#[warn(clippy::empty_line_after_doc_comments)]` on by default
  = help: if the empty line is unintentional, remove it
help: if the comment should document the crate use an inner doc comment
  |
1 - /// ### Auxiliary functions
1 + //! ### Auxiliary functions
  |
help: if the documentation should include the empty line include it in the comment
  |
2 | ///
  |

warning: using tabs in doc comments is not recommended
 --> src/lib.rs:3:4
  |
3 | ///    Function to convert character to digit
  |    ^^^^ help: consider using four spaces per tab
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/rust-1.93.0/index.html#tabs_in_doc_comments
  = note: `#[warn(clippy::tabs_in_doc_comments)]` on by default
2 Likes
3

rustdoc uses <h2> for #, <h3> for ##, <h4> for ###, etc. While <h1> is reserved for function/module/crate name.

4

I have tried various combinations of /// and //! but the line ## Auxiliary functions does not appear!

5

There are multiple problems here.

  • /// documentation applies to the following item. Judging by the text, you probably didn’t mean this, so you need to use //! documentation to apply to the enclosing item, i.e. the module. (This is why Clippy warns about an empty line — because it indicates the documentation might not have been intended to attach to the following item.)

  • fn char_to_digit is not pub, so it and its documentation do not appear in the output by default (unless you specify --document-private-items). That’s why you don’t see the text at all.

  • If you’re trying to insert a header between items in a module — this is not possible. Consider using documentation on mods or impls instead. All documentation is attached to items, not arbitrarily positioned in files.

  • Rustdoc remaps the meaning of #, ##, ### to fit into the structure of the documentation. Each documentation block should use # for its own highest-level heading, not start with ## or ###.

Here is a working code sample you can try documenting to see how the text appears.

pub mod auxiliary {
    //! Auxiliary functions

    /// Convert character to digit
    pub fn char_to_digit(c: char) -> u8 {
        (c as u8) - b'0'
    }
}
7 Likes
6

@kpreid Thanks -- modules are not (yet) appropriate for my pilot project, so I will not yet use intermediate headings.

1 Like