From 99e943c8b84cf2b077223271e4af7981b25f9064 Mon Sep 17 00:00:00 2001 From: steveklabnik Date: Thu, 10 Aug 2017 17:53:36 -0400 Subject: [PATCH 1/5] Document the doc attribute cc #42322 --- src/doc/rustdoc/src/SUMMARY.md | 2 +- src/doc/rustdoc/src/in-source-directives.md | 3 - src/doc/rustdoc/src/the-doc-attribute.md | 108 ++++++++++++++++++++ 3 files changed, 109 insertions(+), 4 deletions(-) delete mode 100644 src/doc/rustdoc/src/in-source-directives.md create mode 100644 src/doc/rustdoc/src/the-doc-attribute.md diff --git a/src/doc/rustdoc/src/SUMMARY.md b/src/doc/rustdoc/src/SUMMARY.md index cd6883a719c..1049cc4284a 100644 --- a/src/doc/rustdoc/src/SUMMARY.md +++ b/src/doc/rustdoc/src/SUMMARY.md @@ -2,7 +2,7 @@ - [What is rustdoc?](what-is-rustdoc.md) - [Command-line arguments](command-line-arguments.md) -- [In-source directives](in-source-directives.md) +- [The `#[doc]` attribute](the-doc-attribute.md) - [Documentation tests](documentation-tests.md) - [Plugins](plugins.md) - [Passes](passes.md) \ No newline at end of file diff --git a/src/doc/rustdoc/src/in-source-directives.md b/src/doc/rustdoc/src/in-source-directives.md deleted file mode 100644 index 83f677fa7f4..00000000000 --- a/src/doc/rustdoc/src/in-source-directives.md +++ /dev/null @@ -1,3 +0,0 @@ -# In-source directives - -Coming soon! \ No newline at end of file diff --git a/src/doc/rustdoc/src/the-doc-attribute.md b/src/doc/rustdoc/src/the-doc-attribute.md new file mode 100644 index 00000000000..18a1814938a --- /dev/null +++ b/src/doc/rustdoc/src/the-doc-attribute.md @@ -0,0 +1,108 @@ +# The `#[doc]` attribute + +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 +are the same: + +```rust,ignore +/// This is a doc comment. +#[doc = "This is a doc comment."] +``` + +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: + +```rust,ignore +#[doc = "This is"] +#[doc = " a "] +#[doc = "doc comment"] +``` + +Which can feel more flexible. + +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. +We've split them into two kinds below: attributes that are useful at the +crate level, and ones that are useful at the item level. + +## At the crate level + +These options control how the docs look at a macro level. + +### `html_favicon_url` + +This form of the `doc` attribute lets you control the favicon of your docs. + +```rust,ignore +#![doc(html_favicon_url = "https://foo.com/favicon.ico")] +``` + +This will put `` into your docs, where +the string for the attribute goes into the `{}`. + +### `html_logo_url` + +This form of the `doc` attribute lets you control the logo in the upper +left hand side of the docs. + +```rust,ignore +#![doc(html_logo_url = "https://foo.com/logo.jpg")] +``` + +This will put `logo` into +your docs, where the string for the attribute goes into the `{}`. + +### `html_playground_url` + +This form of the `doc` attribute lets you control where the "run" buttons +on your documentation examples make requests to. + +```rust,ignore +#![doc(html_playground_url = "https://playground.foo.com/")] +``` + +Now, when you press "run", the button will make a request to this domain. + +### `issue_tracker_base_url` + +This form of the `doc` attribute is mostly only useful for the standard library; +When a feature is unstable, an issue number for tracking the feature must be +given. `rustdoc` uses this number, plus the base URL given here, to link to +the tracking issue. + +```rust,ignore +#![doc(issue_tracker_base_url = "https://github.com/foo/foo/issues/")] +``` + +### `html_no_source` + +By default, `rustdoc` will include the source code of your program, with links +to it in the docs. But if you include this: + +```rust,ignore +#![doc(html_no_source)] +``` + +it will not. + +## At the item level + +These forms of the `#[doc]` attribute are used on individual items, to control how +they are documented. + +## `#[doc(no_inline)]` + +## `#[doc(hidden)]` + +Any item annotated with `#[doc(hidden)]` will not appear in the documentation, unless +the `strip-hidden` pass is removed. + +## `#[doc(primitive)]` + +Since primitive types are defined in the compiler, there's no place to attach documentation +attributes. This attribute is used by the standard library to provide a way to generate +documentation for primitive types. \ No newline at end of file From bc9e0820e74333b0f578d63939c9ab25bc196a1e Mon Sep 17 00:00:00 2001 From: steveklabnik Date: Thu, 10 Aug 2017 18:52:10 -0400 Subject: [PATCH 2/5] doc doc(inline) and doc(no_inline) --- src/doc/rustdoc/src/the-doc-attribute.md | 58 +++++++++++++++++++++++- 1 file changed, 57 insertions(+), 1 deletion(-) diff --git a/src/doc/rustdoc/src/the-doc-attribute.md b/src/doc/rustdoc/src/the-doc-attribute.md index 18a1814938a..013eccab04e 100644 --- a/src/doc/rustdoc/src/the-doc-attribute.md +++ b/src/doc/rustdoc/src/the-doc-attribute.md @@ -94,7 +94,63 @@ it will not. These forms of the `#[doc]` attribute are used on individual items, to control how they are documented. -## `#[doc(no_inline)]` +## `#[doc(no_inline)]`/`#[doc(inline)]` + +These attributes are used on `use` statements, and control where the documentation shows +up. For example, consider this Rust code: + +```rust +pub use bar::Bar; + +/// bar docs +pub mod bar { + /// the docs for Bar + pub struct Bar; +} +``` + +The documentation will generate a "Reexports" section, and say `pub use bar::Bar;`, where +`Bar` is a link to its page. + +If we change the `use` line like this: + +```rust,ignore +#[doc(inline)] +pub use bar::Bar; +``` + +Instead, `Bar` will appear in a `Structs` section, just like `Bar` was defined at the +top level, rather than `pub use`'d. + +Let's change our original example, by making `bar` private: + +```rust +pub use bar::Bar; + +/// bar docs +mod bar { + /// the docs for Bar + pub struct Bar; +} +``` + +Here, because `bar` is not public, `Bar` wouldn't have its own page, so there's nowhere +to link to. `rustdoc` will inline these definitions, and so we end up in the same case +as the `#[doc(inline)]` above; `Bar` is in a `Structs` section, as if it were defined at +the top level. If we add the `no_inline` form of the attribute: + +```rust +#[doc(no_inline)] +pub use bar::Bar; + +/// bar docs +mod bar { + /// the docs for Bar + pub struct Bar; +} +``` + +Now we'll have a `Reexports` line, and `Bar` will not link to anywhere. ## `#[doc(hidden)]` From 640cf596ec1eb6efb30232df6222d927d814bffb Mon Sep 17 00:00:00 2001 From: steveklabnik Date: Thu, 10 Aug 2017 18:59:51 -0400 Subject: [PATCH 3/5] 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 013eccab04e..0b14f44b63e 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. From 92f84424345c72ab5d7b13e931d09d62f8543038 Mon Sep 17 00:00:00 2001 From: steveklabnik Date: Thu, 10 Aug 2017 20:17:41 -0400 Subject: [PATCH 4/5] ignore more things --- src/doc/rustdoc/src/the-doc-attribute.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/doc/rustdoc/src/the-doc-attribute.md b/src/doc/rustdoc/src/the-doc-attribute.md index 0b14f44b63e..b77565ec2d7 100644 --- a/src/doc/rustdoc/src/the-doc-attribute.md +++ b/src/doc/rustdoc/src/the-doc-attribute.md @@ -107,7 +107,7 @@ they are documented. These attributes are used on `use` statements, and control where the documentation shows up. For example, consider this Rust code: -```rust +```rust,ignore pub use bar::Bar; /// bar docs @@ -132,7 +132,7 @@ top level, rather than `pub use`'d. Let's change our original example, by making `bar` private: -```rust +```rust,ignore pub use bar::Bar; /// bar docs @@ -147,7 +147,7 @@ to link to. `rustdoc` will inline these definitions, and so we end up in the sam as the `#[doc(inline)]` above; `Bar` is in a `Structs` section, as if it were defined at the top level. If we add the `no_inline` form of the attribute: -```rust +```rust,ignore #[doc(no_inline)] pub use bar::Bar; @@ -169,4 +169,4 @@ the `strip-hidden` pass is removed. Since primitive types are defined in the compiler, there's no place to attach documentation attributes. This attribute is used by the standard library to provide a way to generate -documentation for primitive types. \ No newline at end of file +documentation for primitive types. From 1e4aaea431a7fb87a54fd3dd9600c8a346744ff2 Mon Sep 17 00:00:00 2001 From: steveklabnik Date: Fri, 11 Aug 2017 16:24:18 -0400 Subject: [PATCH 5/5] address review feedback --- src/doc/rustdoc/src/the-doc-attribute.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/src/doc/rustdoc/src/the-doc-attribute.md b/src/doc/rustdoc/src/the-doc-attribute.md index b77565ec2d7..978d7656bdd 100644 --- a/src/doc/rustdoc/src/the-doc-attribute.md +++ b/src/doc/rustdoc/src/the-doc-attribute.md @@ -46,35 +46,41 @@ These options control how the docs look at a macro level. This form of the `doc` attribute lets you control the favicon of your docs. ```rust,ignore -#![doc(html_favicon_url = "https://foo.com/favicon.ico")] +#![doc(html_favicon_url = "https://example.com/favicon.ico")] ``` This will put `` into your docs, where the string for the attribute goes into the `{}`. +If you don't use this attribute, there will be no favicon. + ### `html_logo_url` This form of the `doc` attribute lets you control the logo in the upper left hand side of the docs. ```rust,ignore -#![doc(html_logo_url = "https://foo.com/logo.jpg")] +#![doc(html_logo_url = "https://example.com/logo.jpg")] ``` This will put `logo` into your docs, where the string for the attribute goes into the `{}`. +If you don't use this attribute, there will be no logo. + ### `html_playground_url` This form of the `doc` attribute lets you control where the "run" buttons on your documentation examples make requests to. ```rust,ignore -#![doc(html_playground_url = "https://playground.foo.com/")] +#![doc(html_playground_url = "https://playground.example.com/")] ``` Now, when you press "run", the button will make a request to this domain. +If you don't use this attribute, there will be no run buttons. + ### `issue_tracker_base_url` This form of the `doc` attribute is mostly only useful for the standard library; @@ -83,7 +89,7 @@ given. `rustdoc` uses this number, plus the base URL given here, to link to the tracking issue. ```rust,ignore -#![doc(issue_tracker_base_url = "https://github.com/foo/foo/issues/")] +#![doc(issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/")] ``` ### `html_no_source`