Search code examples
rustdocumentationrustdoc

Target binary file level generated documentation in Rust project


I have a Rust project consisting of two binary sources sharing the same library:

Cargo.toml:

<...>

[[bin]]
name = "quoter_xml"
path = "src/quoter_xml.rs"

[[bin]]
name = "quoter"
path = "src/quoter.rs"

<...>

src/quoter_xml.rs:

use <...>

fn main() {
    <...>
}

src/quoter.rs:

use <...>

fn main() {
    <...>
}

src/lib.rs:

pub mod <...>

When I compile it, I get two binaries: quoter_xml and quoter_xml.
When I generate doc using cargo doc, I get independent doc files doc/quoter_xml/index.html and doc/quoter/index.html.

What I want is to add some description texts to the top of these doc files. I've tried to add "//!"-type comments to binary sources, for example:

src/quoter_xml.rs:

use <...>

//! quoter_xml - this binary is for <..>

fn main() {
    <...>
}

But if I compile project after it, I get an error:

error[E0753]: expected outer doc comment
  --> src/quoter_xml.rs:10:1
   |
10 | //! quoter_xml - this binary is for <..>
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: inner doc comments like this (starting with `//!` or `/*!`) can only appear before items
help: you might have meant to write a regular comment
   |
10 - //! quoter_xml - this binary is for <..>
10 + // quoter_xml - this binary is for <..>
   | 

Compiler consider to use regular comments, but I don't want it: I need comments that will get to the top of doc pages, "//!"-type comments.

I've search Internet and found recommendation to place these type of comments in src/lib.rs file, but this is not what I want. I want to have independent top-level comments in doc for each binary file.

Any suggestion?


Solution

  • I believe you simply need to move your comment above the use statement in quoter_xml.rs.

    //! quoter_xml - this binary is for <..>
    
    use <...>
    
    // Crate level doc comment cannot be after any code.
    
    fn main() {
        <...>
    }