rustdoc is the documentation generator for the Rust programming language.
Questions tagged [rustdoc]
75 questions
76
votes
5 answers
How to link to other fns/structs/enums/traits in rustdoc?
I'm building a Rust library and want to give it some polish. In the rustdoc, I'd sometimes like to link to other parts of the library within the docs, e.g. fns, traits or structs. What is the official syntax for this?
llogiq
- 13,815
- 8
- 40
- 72
49
votes
3 answers
How do you document function arguments?
rustdoc allows you to document struct fields and enum variants by including a doc comment above each line:
enum Choices {
/// The first choice.
First,
/// The second choice.
Second,
}
struct Person {
/// The person's name.
name:…
Jimmy
- 35,686
- 13
- 80
- 98
28
votes
2 answers
How do I prevent `rust doc` from adding dependencies to documentation?
I've just started playing with Rust and was trying to generate docs for the code I've written. When I issued cargo doc, I saw something a little weird.
21:53 $ cargo doc
Compiling regex-syntax v0.2.2
Compiling libc v0.2.2
Compiling memchr…
erip
- 16,374
- 11
- 66
- 121
23
votes
2 answers
How to get a feature requirement tag in the documentation generated by `cargo doc`?
If you look at the Tokio docs on docs.rs there's a blue tag indicating that a feature must be activated in order to access this API:
I would like to enable this for my crate as well, how can this be done?
SBSTP
- 3,479
- 6
- 30
- 41
15
votes
1 answer
Difference between `cargo doc` and `cargo rustdoc`
According to doc.rust-lang.org
cargo rustdoc
build[s] a package's documentation, using specified custom flags
cargo doc
build[s] a package's documentation
What is the difference between the two? From what I understand cargo rustdoc is just…
andrewgazelka
- 1,746
- 1
- 16
- 26
14
votes
2 answers
Is there a way to hide a macro pattern from docs?
As of Rust 1.6.0, the generated documentation hides the implementation of each macro pattern:
Is there a way to hide some of the patterns from the Cargo-generated docs?
macro_rules! mc {
// hide this entire pattern
(@impl, $arg:expr) => {…
dragostis
- 2,574
- 2
- 20
- 39
11
votes
2 answers
Unresolved import in documentation example
I'm having difficulty fixing an error inside my documentation example for my library. I have the file structure like for my crate bignum
.
|-- Cargo.lock
|-- Cargo.toml
|-- examples
| |-- dat
| | `-- euler_13.dat
| |-- debug.rs
| `--…
Syntactic Fructose
- 18,936
- 23
- 91
- 177
10
votes
1 answer
How to include ASCII art/diagrams in Rust source-code comment documentation?
How should Markdown be used with rustdoc to include diagrams or ASCII art?
From reading the manual, triple back-ticks can be used for code-snippets.
How do I include literal, non-formatted text?
(Something like Doxygen's
...)
ideasman42
- 42,413
- 44
- 197
- 320
9
votes
1 answer
Generate markdown docs with rustdoc?
Is there any way to generate a single markdown file in doc/ from the /// comments?
Multiple markdown files (doc/main.md, doc/foo.md, etc) would be nice too.
I'm new to rust, and while the generated HTML documentation is nice, I mostly live on the…
cas
- 735
- 7
- 19
8
votes
1 answer
How to include an arbitrary markdown file as a documentation attribute?
If the readme Cargo.toml key is set, doc.rs renders the README on the crate's index page. Is there a way to emulate this when running cargo doc locally?
If I add:
#![doc = r###"contents
of
README.md
here
"###]
as a literal, I get the behaviour I'm…
Daniel Wagner-Hall
- 2,446
- 1
- 20
- 18
8
votes
1 answer
How to generate documentation for private items
I have a project with:
main.rs
module_1/mod.rs
module_2/mod.rs
module_2/module_3/mod.rs
when I run cargo doc, I have just documentation for main.rs, not for modules.
In my main.rs I have:
mod module_1;
mod module_2;
fn main() {
...
}
I have tried…
bubulemaster
- 221
- 2
- 8
7
votes
1 answer
Documenting a public concrete variant of a private generic type
In another question of mine, I asked how to publicly expose only a concrete variant (Foo) of a private generic type (Foo). The suggested solution is as follows:
mod internal {
/// Private documentation of `Foo`.
pub struct Foo {
…
Florian Brucker
- 9,621
- 3
- 48
- 81
6
votes
0 answers
Find structs that implement a given set of traits
I've come across a case where I have a generic that needs to satisfy two traits.
pub struct FileReader { /* private fields */ }
These are standard traits and I can find their implementors individually. Then I can see which…
twitu
- 553
- 6
- 12
6
votes
2 answers
Break long table rows into multiple lines in documentation
I want to document my crate and include a table in the documentation:
//! Demonstrating MarkDown tables.
//!
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president | I can't think of any…
Lukas Kalbertodt
- 79,749
- 26
- 255
- 305
6
votes
2 answers
How to put a line into the documentation which is ignored for doc tests?
How can I write a line into the documenation code but let the compiler ignore it?
I want to write
/// # Examples
///
/// To clone something, do
///
/// ```
/// IGNORE_FOR_COMPILATION_BUT_SHOW: let cloned = myValue.clone();
/// # let cloned =…
torkleyy
- 1,137
- 9
- 26