OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

review feedback

Browse Source
This commit is contained in:
steveklabnik 2017-08-10 18:59:51 -04:00
parent bc9e0820e7
commit 640cf596ec
1 changed files with 12 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
src/doc/rustdoc/src/the-doc-attribute.md
View File

@ -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.