From 640cf596ec1eb6efb30232df6222d927d814bffb Mon Sep 17 00:00:00 2001 From: steveklabnik Date: Thu, 10 Aug 2017 18:59:51 -0400 Subject: [PATCH] review feedback --- src/doc/rustdoc/src/the-doc-attribute.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/doc/rustdoc/src/the-doc-attribute.md b/src/doc/rustdoc/src/the-doc-attribute.md index 013eccab04eb..0b14f44b63e8 100644 --- a/src/doc/rustdoc/src/the-doc-attribute.md +++ b/src/doc/rustdoc/src/the-doc-attribute.md @@ -3,15 +3,17 @@ The `#[doc]` attribute lets you control various aspects of how `rustdoc` does its job. -The most basic job of `#[doc]` is to be the way that the text of the documentation -is handled. That is, `///` is syntax sugar for `#[doc]`. This means that these two +The most basic function of `#[doc]` is to handle the actual documentation +text. That is, `///` is syntax sugar for `#[doc]`. This means that these two are the same: ```rust,ignore /// This is a doc comment. -#[doc = "This is a doc comment."] +#[doc = " This is a doc comment."] ``` +(Note the leading space in the attribute version.) + In most cases, `///` is easier to use than `#[doc]`. One case where the latter is easier is when generating documentation in macros; the `collapse-docs` pass will combine multiple `#[doc]` attributes into a single doc comment, letting you generate code like this: @@ -22,7 +24,13 @@ when generating documentation in macros; the `collapse-docs` pass will combine m #[doc = "doc comment"] ``` -Which can feel more flexible. +Which can feel more flexible. Note that this would generate this: + +```rust,ignore +#[doc = "This is\n a \ndoc comment"] +``` + +but given that docs are rendered via Markdown, it will remove these newlines. The `doc` attribute has more options though! These don't involve the text of the output, but instead, various aspects of the presentation of the output.