Improving std::env docs
Addresses #29351.
Hopefully this addresses the following points:
> - iterators should use the standard iterator boilerplate like https://doc.rust-lang.org/std/iter/struct.Map.html, this applies to all structs except for JoinPathsError
> - JoinPathsError should properly link the function it comes from and use language similar to https://doc.rust-lang.org/std/io/struct.Error.html
> - same wording issues with VarError
> - functions need to ensure linkage to things they refer to in their descriptions
> - Explain the difference between `os` and non-`os` structs and methods
Correct some stability versions
These were found by running tidy on stable versions of rust and finding
features stabilised with the wrong version numbers.
Improve the error management when /proc is not mounted
This PR does two things:
* Triggers an error on GNU/Linux & Android when /proc/self/exe doesn't exist
* Handle the error properly
Improve docs in os::windows::ffi and os::windows::fs
Part of #29367
This PR makes changes to the documentation in `os::windows::ffi` and `os::windows::fs` with the goal of fleshing them out and bringing them in line with Rust's quality standards.
r? @steveklabnik
- Remove `()` parens when referencing functions in docs.
- Change some examples to be no_run instead of ignore.
- Normalize style in examples for `OpenOptionsExt`.
- Fix typo in windows mod docs.
[Doc] Add links to the `thread::LocalKey` doc.
Part of #29378 .
I do not know exactly what should be done for the `cleanup` part, if you have any idea I'll gladly do it.
r? @rust-lang/docs
[Doc] Implrove `thread::Builder`'s doc.
Part of #29378 .
- Explains *why* we would use the builder instead ofthe free function.
- Changes the parent-child explanation for a spawned-caller in `thread::Builder::spawn`
- Adds a link to `io::Result` in `thread::Builder`
- Corrects the return type doc in `thread::Builder::spawn`
r? @rust-lang/docs
Part of #29378 .
- In particular explains *why* we would use the builder instead of
the free function.
- Changes the parent-child explanation for a spawned-caller.
- Add link to `io::Result` in `thread::Builder`
- Corrects the `thread::Builder::spawn` documentation.
Windows io::Error: also format NTSTATUS error codes
`NTSTATUS` errors may be encoded as `HRESULT`, see [[MS-ERREF]](https://msdn.microsoft.com/en-us/library/cc231198.aspx). These error codes can still be formatted using `FormatMessageW` but require some different parameters to be passed in.
I wasn't sure if this needed a test and if so, how to test it. Presumably we wouldn't want to make our tests dependent on localization-dependent strings returned from `FormatMessageW`.
Users that get an `err: NTSTATUS` will need to do `io::Error::from_raw_os_error(err|0x1000_0000)` (the equivalent of [`HRESULT_FROM_NT`](https://msdn.microsoft.com/en-us/library/ms693780(VS.85).aspx))
Add `eprint!` and `eprintln!` macros to the prelude.
These are exactly the same as `print!` and `println!` except that they write to stderr instead of stdout. Issues #39228 and #40528; previous PR #39229; accepted RFC rust-lang/rfcs#1869; proposed revision to The Book rust-lang/book#615.
I have _not_ revised this any since the original submission; I will do that later this week. I wanted to get this PR in place since it's been quite a while since the RFC was merged.
Known outstanding review comments:
* [x] @steveklabnik requested a new chapter for the unstable version of The Book -- please see if the proposed revisions to the second edition cover it.
* [x] @nodakai asked if it were possible to merge the internal methods `_print` and `_eprint` - not completely, since they both refer to different internal globals which we don't want to expose, but I will see if some duplication can be factored out.
Please let me know if I missed anything.
[Doc] Improve `thread::spawn` documentation
Part of #29378
- Add two examples to `thread::spawn` doumentation that show common uses of threads.
- Add a link to `thread::Builder` in the `thread::spawn` documentation for configuring threads.
- Add a link to `thread::spawn` in `thread::Builder` in order to avoid documentation duplication.
r? @steveklabnik
[DOC] Improve the thread::park and thread::unpark documentation
Part of #29378 .
Takes care of the documentation for `park`, `park_duration` and also improves the `unpark` example.
- `park should` have its module documentation inlined here, and cleaned up.
- `park_timeout` could use links to `park`.
Add more ways to create a PathBuf to docs
The best way to do this wasn't in the documentation, and the ways that
were there needed some extra text to elaborate.
Fixes#40159
/cc @nagisa
* Factor out the nigh-identical bodies of `_print` and `_eprint` to a helper
function `print_to` (I was sorely tempted to call it `_doprnt`).
* Update the issue number for the unstable `eprint` feature.
* Add entries to the "unstable book" for `eprint` and `eprint_internal`.
* Style corrections to the documentation.
Improve cleaning of the bottom of the backtrace
Following https://github.com/rust-lang/rust/pull/40264. It only cleans the bottom of the trace (after the main). It handles correctly the normal main, tests, benchmarks and threads.
I kept `skipped_before` since it will be used later for the cleaning of the top.
When `RUST_BACKTRACE=1`, remove all frames after
`__rust_maybe_catch_panic`. Tested on `main`, threads, tests and
benches. Cleaning of the top of the stacktrace is let to a future PR.
Fixes#40201
See #41815
