mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #117932 - GuillaumeGomez:update-rustdoc-book, r=notriddle

Browse Source 
Correct rustdoc section where we talk about rustdoc emitting errors on invalid code

As discussed on [zulip](https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc/topic/stop.20accepting.20broken.20code/near/401760318).

r? `@notriddle`
This commit is contained in:
Trevor Gross 2024-07-22 11:40:18 -05:00 committed by GitHub
commit a42b99384d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 2 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
src/doc/rustdoc/src/advanced-features.md
View File

@ -38,33 +38,10 @@ they will both appear in documentation.
Rustdoc does not have a magic way to compile documentation 'as-if' you'd run it once for each Rustdoc does not have a magic way to compile documentation 'as-if' you'd run it once for each
platform (such a magic wand has been called the ['holy grail of rustdoc'][#1998]). Instead, platform (such a magic wand has been called the ['holy grail of rustdoc'][#1998]). Instead,
it sees *all* of your code at once, the same way the Rust compiler would if you passed it it sees *all* of your code at once, the same way the Rust compiler would if you passed it
`--cfg doc`. However, Rustdoc has a trick up its sleeve to handle platform-specific code if it `--cfg doc`. The main difference is that rustdoc doesn't run all the compiler passes, meaning
*does* receive it. that some invalid code won't emit an error.
To document your crate, Rustdoc only needs to know the public signature of your functions.
In particular, it doesn't have to know how any of your functions are implemented, so it ignores
all type errors and name resolution errors with function bodies. Note that this does *not*
work for anything outside a function body: since Rustdoc documents your types, it has to
know what those types are! For example, this code will work regardless of the platform:
```rust,ignore (platform-specific,rustdoc-specific-behavior)
pub fn f() {
use std::os::windows::ffi::OsStrExt;
}
```
but this will not, because the unknown type is part of the function signature:
```rust,ignore (platform-specific,rustdoc-specific-behavior)
pub fn f() -> std::os::windows::ffi::EncodeWide<'static> {
unimplemented!()
}
```
For a more realistic example of code this allows, see [the rustdoc test suite][realistic-async].
[#1998]: https://github.com/rust-lang/rust/issues/1998 [#1998]: https://github.com/rust-lang/rust/issues/1998
[realistic-async]: https://github.com/rust-lang/rust/blob/b146000e910ccd60bdcde89363cb6aa14ecc0d95/src/test/rustdoc-ui/error-in-impl-trait/realistic-async.rs
## Add aliases for an item in documentation search ## Add aliases for an item in documentation search