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?
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() {
<...>
}