diff --git a/src/ch04-05-comments.md b/src/ch04-05-comments.md index cb8eaf3..a4c950b 100644 --- a/src/ch04-05-comments.md +++ b/src/ch04-05-comments.md @@ -39,57 +39,3 @@ fn main() { ``` That’s all there is to it. Comments are not particularly complicated. - -### 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 can read documentation comments and -produce HTML documentation from them. This documentation's intended audience is -usually people who are using your code, so that they know how to interact with -it. Regular comments won't be shown in `rustdoc` generated HTML, so their -intended audience is people who are reading and editing your code. - -Documentation comments use an extra slash, like this: - -```rust -/// The foo function doesn’t really do much. -fn foo() { - -} - -/// Documentation comments can use -/// multiple line comments too, -/// like we did before. -fn bar() { - -} -``` - -The `rustdoc` tool will interpret each comment in this example as documenting -the thing that follows it. The first comment would be used to document the -`foo()` function and the second comment would document the `bar()` function. - -Because documentation comments have semantic meaning to `rustdoc`, the compiler -will pay attention to the placement of your documentation comments. For -example, a program containing only this: - -```rust,ignore -/// What am I documenting? -``` - -Will give the following compiler error: - -```bash -src/main.rs:1:1: 1:27 error: expected item after doc comment -src/main.rs:1 /// What am I documenting? - ^~~~~~~~~~~~~~~~~~~~~~~~~~ -``` - -This happens because Rust expects a document comment to be associated with -whatever code comes directly after it, so it sees that a document comment alone -must be a mistake. - -Providing documentation for libraries is a best practice that the Rust community -strives to do to be helpful to each other. We'll cover how you can generate -great API documentation for your library in more detail in Chapter XX.