diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 864c33f..1edbc14 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -81,8 +81,10 @@ - [Using Rust from Other Languages]() - [`static`]() -- [Cargo]() +- [Creating a Library]() + - [Cargo]() - [Crates.io]() + - [Documentation](chYY-YY-documentation.md) - [Advanced Type System Features]() - [Associated Types]() diff --git a/src/ch03-06-comments.md b/src/ch03-06-comments.md index 7a96ae3..8899548 100644 --- a/src/ch03-06-comments.md +++ b/src/ch03-06-comments.md @@ -37,43 +37,3 @@ fn main() { ``` That’s all there is to it. Comments are not particularly complicated. - -## Documentation comments - -However, Rust has another kind of comment: a documentation comment. These -comments don’t affect the way that the code works, but they do work with Rust’s -tools. More specifically, the `rustdoc` tool that comes with Rust reads -documentation comments and produces HTML documentation from them. - -Documentation comments use an extra slash: - -```rust -/// The foo function doesn’t really do much. -fn foo() { -} - -/// We also can use -/// multiple comments here too, -/// like we did before -fn bar() { -} -``` - -This comment would then be interpreted by `rustdoc` as documenting the thing -that follows it: `foo()` and `bar()`. - -Because documentation comments have semantic meaning to `rustdoc`, the compiler -will pay attention to the placement of your documentation comments. For -example, a program with only this: - -```rust,ignore -/// What am I documenting? -``` - -Will give a compiler error: - -```text -src/main.rs:1:1: 1:27 error: expected item after doc comment -src/main.rs:1 /// What am I documenting? - ^~~~~~~~~~~~~~~~~~~~~~~~~~ -``` diff --git a/src/chYY-YY-documentation.md b/src/chYY-YY-documentation.md new file mode 100644 index 0000000..1adb89e --- /dev/null +++ b/src/chYY-YY-documentation.md @@ -0,0 +1,45 @@ +## Documentation + + + +### Documentation comments + +Rust has another kind of comment: a documentation comment. These +comments don’t affect the way that the code works, but they do work with Rust’s +tools. More specifically, the `rustdoc` tool that comes with Rust reads +documentation comments and produces HTML documentation from them. + +Documentation comments use an extra slash: + +```rust +/// The foo function doesn’t really do much. +fn foo() { +} + +/// We also can use +/// multiple comments here too, +/// like we did before +fn bar() { +} +``` + +This comment would then be interpreted by `rustdoc` as documenting the thing +that follows it: `foo()` and `bar()`. + +Because documentation comments have semantic meaning to `rustdoc`, the compiler +will pay attention to the placement of your documentation comments. For +example, a program with only this: + +```rust,ignore +/// What am I documenting? +``` + +Will give a compiler error: + +```text +src/main.rs:1:1: 1:27 error: expected item after doc comment +src/main.rs:1 /// What am I documenting? + ^~~~~~~~~~~~~~~~~~~~~~~~~~ +``` + +### Generating HTML documentation