@@ -56,88 +56,6 @@ It is also not emitted for foreign items, aliases, extern crates and imports.
56
56
These features operate by extending the ` #[doc] ` attribute, and thus can be caught by the compiler
57
57
and enabled with a ` #![feature(...)] ` attribute in your crate.
58
58
59
- ### ` #[doc(cfg)] ` : Recording what platforms or features are required for code to be present
60
-
61
- * Tracking issue: [ #43781 ] ( https://github.com/rust-lang/rust/issues/43781 )
62
-
63
- You can use ` #[doc(cfg(...))] ` to tell Rustdoc exactly which platform items appear on.
64
- This has two effects:
65
-
66
- 1 . doctests will only run on the appropriate platforms, and
67
- 2 . When Rustdoc renders documentation for that item, it will be accompanied by a banner explaining
68
- that the item is only available on certain platforms.
69
-
70
- ` #[doc(cfg)] ` is intended to be used alongside [ ` #[cfg(doc)] ` ] [ cfg-doc ] .
71
- For example, ` #[cfg(any(windows, doc))] ` will preserve the item either on Windows or during the
72
- documentation process. Then, adding a new attribute ` #[doc(cfg(windows))] ` will tell Rustdoc that
73
- the item is supposed to be used on Windows. For example:
74
-
75
- ``` rust
76
- #![feature(doc_cfg)]
77
-
78
- /// Token struct that can only be used on Windows.
79
- #[cfg(any(windows, doc))]
80
- #[doc(cfg(windows))]
81
- pub struct WindowsToken ;
82
-
83
- /// Token struct that can only be used on Unix.
84
- #[cfg(any(unix, doc))]
85
- #[doc(cfg(unix))]
86
- pub struct UnixToken ;
87
-
88
- /// Token struct that is only available with the `serde` feature
89
- #[cfg(feature = " serde" )]
90
- #[doc(cfg(feature = " serde" ))]
91
- #[derive(serde:: Deserialize )]
92
- pub struct SerdeToken ;
93
- ```
94
-
95
- In this sample, the tokens will only appear on their respective platforms, but they will both appear
96
- in documentation.
97
-
98
- ` #[doc(cfg(...))] ` was introduced to be used by the standard library and currently requires the
99
- ` #![feature(doc_cfg)] ` feature gate. For more information, see [ its chapter in the Unstable
100
- Book] [ unstable-doc-cfg ] and [ its tracking issue] [ issue-doc-cfg ] .
101
-
102
- ### ` doc_auto_cfg ` : Automatically generate ` #[doc(cfg)] `
103
-
104
- * Tracking issue: [ #43781 ] ( https://github.com/rust-lang/rust/issues/43781 )
105
-
106
- ` doc_auto_cfg ` is an extension to the ` #[doc(cfg)] ` feature. With it, you don't need to add
107
- ` #[doc(cfg(...)] ` anymore unless you want to override the default behaviour. So if we take the
108
- previous source code:
109
-
110
- ``` rust
111
- #![feature(doc_auto_cfg)]
112
-
113
- /// Token struct that can only be used on Windows.
114
- #[cfg(any(windows, doc))]
115
- pub struct WindowsToken ;
116
-
117
- /// Token struct that can only be used on Unix.
118
- #[cfg(any(unix, doc))]
119
- pub struct UnixToken ;
120
-
121
- /// Token struct that is only available with the `serde` feature
122
- #[cfg(feature = " serde" )]
123
- #[derive(serde:: Deserialize )]
124
- pub struct SerdeToken ;
125
- ```
126
-
127
- It'll render almost the same, the difference being that ` doc ` will also be displayed. To fix this,
128
- you can use ` doc_cfg_hide ` :
129
-
130
- ``` rust
131
- #![feature(doc_cfg_hide)]
132
- #![doc(cfg_hide(doc))]
133
- ```
134
-
135
- And ` doc ` won't show up anymore!
136
-
137
- [ cfg-doc ] : ./advanced-features.md
138
- [ unstable-doc-cfg ] : ../unstable-book/language-features/doc-cfg.html
139
- [ issue-doc-cfg ] : https://github.com/rust-lang/rust/issues/43781
140
-
141
59
### Adding your trait to the "Notable traits" dialog
142
60
143
61
* Tracking issue: [ #45040 ] ( https://github.com/rust-lang/rust/issues/45040 )
0 commit comments