]>
Commit | Line | Data |
---|---|---|
29967ef6 | 1 | # Advanced features |
60c5eb7d XL |
2 | |
3 | The features listed on this page fall outside the rest of the main categories. | |
4 | ||
29967ef6 | 5 | ## `#[cfg(doc)]`: Documenting platform-specific or feature-specific information |
60c5eb7d | 6 | |
ba9703b0 | 7 | For conditional compilation, Rustdoc treats your crate the same way the compiler does. Only things |
60c5eb7d XL |
8 | from the host target are available (or from the given `--target` if present), and everything else is |
9 | "filtered out" from the crate. This can cause problems if your crate is providing different things | |
10 | on different targets and you want your documentation to reflect all the available items you | |
11 | provide. | |
12 | ||
13 | If you want to make sure an item is seen by Rustdoc regardless of what platform it's targeting, | |
14 | you can apply `#[cfg(doc)]` to it. Rustdoc sets this whenever it's building documentation, so | |
15 | anything that uses that flag will make it into documentation it generates. To apply this to an item | |
16 | with other `#[cfg]` filters on it, you can write something like `#[cfg(any(windows, doc))]`. | |
17 | This will preserve the item either when built normally on Windows, or when being documented | |
18 | anywhere. | |
19 | ||
29967ef6 | 20 | Please note that this `cfg` is not passed to doctests. |
60c5eb7d XL |
21 | |
22 | Example: | |
23 | ||
24 | ```rust | |
25 | /// Token struct that can only be used on Windows. | |
26 | #[cfg(any(windows, doc))] | |
27 | pub struct WindowsToken; | |
28 | /// Token struct that can only be used on Unix. | |
29 | #[cfg(any(unix, doc))] | |
30 | pub struct UnixToken; | |
31 | ``` | |
32 | ||
33 | Here, the respective tokens can only be used by dependent crates on their respective platforms, but | |
34 | they will both appear in documentation. | |
1b1a35ee | 35 | |
29967ef6 XL |
36 | ### Interactions between platform-specific docs |
37 | ||
38 | Rustdoc does not have a magic way to compile documentation 'as-if' you'd run it once for each | |
39 | platform (such a magic wand has been called the ['holy grail of rustdoc'][#1998]). Instead, | |
40 | it sees *all* of your code at once, the same way the Rust compiler would if you passed it | |
41 | `--cfg doc`. However, Rustdoc has a trick up its sleeve to handle platform-specific code if it | |
42 | *does* receive it. | |
43 | ||
44 | To document your crate, Rustdoc only needs to know the public signature of your functions. | |
45 | In particular, it doesn't have to know how any of your functions are implemented, so it ignores | |
46 | all type errors and name resolution errors with function bodies. Note that this does *not* | |
47 | work for anything outside a function body: since Rustdoc documents your types, it has to | |
48 | know what those types are! For example, this code will work regardless of the platform: | |
49 | ||
6a06907d | 50 | ```rust,ignore (platform-specific,rustdoc-specific-behavior) |
29967ef6 XL |
51 | pub fn f() { |
52 | use std::os::windows::ffi::OsStrExt; | |
53 | } | |
54 | ``` | |
55 | ||
56 | but this will not, because the unknown type is part of the function signature: | |
57 | ||
6a06907d | 58 | ```rust,ignore (platform-specific,rustdoc-specific-behavior) |
29967ef6 XL |
59 | pub fn f() -> std::os::windows::ffi::EncodeWide<'static> { |
60 | unimplemented!() | |
61 | } | |
62 | ``` | |
63 | ||
64 | For a more realistic example of code this allows, see [the rustdoc test suite][realistic-async]. | |
65 | ||
66 | [#1998]: https://github.com/rust-lang/rust/issues/1998 | |
67 | [realistic-async]: https://github.com/rust-lang/rust/blob/b146000e910ccd60bdcde89363cb6aa14ecc0d95/src/test/rustdoc-ui/error-in-impl-trait/realistic-async.rs | |
68 | ||
1b1a35ee XL |
69 | ## Add aliases for an item in documentation search |
70 | ||
71 | This feature allows you to add alias(es) to an item when using the `rustdoc` search through the | |
72 | `doc(alias)` attribute. Example: | |
73 | ||
74 | ```rust,no_run | |
75 | #[doc(alias = "x")] | |
76 | #[doc(alias = "big")] | |
77 | pub struct BigX; | |
78 | ``` | |
79 | ||
80 | Then, when looking for it through the `rustdoc` search, if you enter "x" or | |
81 | "big", search will show the `BigX` struct first. | |
82 | ||
83 | There are some limitations on the doc alias names though: you can't use `"` or whitespace. | |
6a06907d XL |
84 | |
85 | You can add multiple aliases at the same time by using a list: | |
86 | ||
87 | ```rust,no_run | |
88 | #[doc(alias("x", "big"))] | |
89 | pub struct BigX; | |
90 | ``` | |
5e7ed085 FG |
91 | |
92 | ## Custom search engines | |
93 | ||
94 | If you find yourself often referencing online Rust docs you might enjoy using a custom search | |
95 | engine. This allows you to use the navigation bar directly to search a `rustdoc` website. | |
96 | Most browsers support this feature by letting you define a URL template containing `%s` | |
97 | which will be substituted for the search term. As an example, for the standard library you could use | |
98 | this template: | |
99 | ||
100 | ```text | |
101 | https://doc.rust-lang.org/stable/std/?search=%s | |
102 | ``` | |
103 | ||
104 | Note that this will take you to a results page listing all matches. If you want to navigate to the first | |
105 | result right away (which is often the best match) use the following instead: | |
106 | ||
107 | ```text | |
108 | https://doc.rust-lang.org/stable/std/?search=%s&go_to_first=true | |
109 | ``` | |
110 | ||
111 | This URL adds the `go_to_first=true` query parameter which can be appended to any `rustdoc` search URL | |
112 | to automatically go to the first result. | |
ed00b5ec FG |
113 | |
114 | ## `#[repr(transparent)]`: Documenting the transparent representation | |
115 | ||
116 | You can read more about `#[repr(transparent)]` itself in the [Rust Reference][repr-trans-ref] and | |
117 | in the [Rustonomicon][repr-trans-nomicon]. | |
118 | ||
119 | Since this representation is only considered part of the public ABI if the single field with non-trivial | |
120 | size or alignment is public and if the documentation does not state otherwise, Rustdoc helpfully displays | |
121 | the attribute if and only if the non-1-ZST field is public or at least one field is public in case all | |
122 | fields are 1-ZST fields. The term *1-ZST* refers to types that are one-aligned and zero-sized. | |
123 | ||
124 | It would seem that one can manually hide the attribute with `#[cfg_attr(not(doc), repr(transparent))]` | |
125 | if one wishes to declare the representation as private even if the non-1-ZST field is public. | |
126 | However, due to [current limitations][cross-crate-cfg-doc], this method is not always guaranteed to work. | |
127 | Therefore, if you would like to do so, you should always write it down in prose independently of whether | |
128 | you use `cfg_attr` or not. | |
129 | ||
130 | [repr-trans-ref]: https://doc.rust-lang.org/reference/type-layout.html#the-transparent-representation | |
131 | [repr-trans-nomicon]: https://doc.rust-lang.org/nomicon/other-reprs.html#reprtransparent | |
132 | [cross-crate-cfg-doc]: https://github.com/rust-lang/rust/issues/114952 |