rustdoc: Sort lines in search index and implementors js
This means the files are generated deterministically even with rustdoc running in parallel.
Fixes the first part of #30220.
rustdoc: get back missing crate-name when --playground-url is used
follow up PR #37763
r? @alexcrichton (since you r+ed to #37763 )
----
Edit: When `#![doc(html_playground_url="")]` is used, the current crate name is saved to `PLAYGROUND`, so rustdoc may generate `extern crate NAME;` into code snips automatically. But when `--playground-url` was introduced in PR #37763, I forgot saving crate name to `PLAYGROUND`. This PR fix that.
----
Update:
- add test
- unstable `--playground-url`
rustdoc: Remove unnecessary stability versions
For some reason only on enum and macro pages, the stability version is
rendered after the summary unlike all other pages. As it is already
displayed at the top of the page for all items, this removes it for
consistency and to prevent it from overlapping the summary text.
Fixes#36093
For some reason only on enum and macro pages, the stability version is
rendered after the summary unlike all other pages. As it is already
displayed at the top of the page for all items, this removes it for
consistency and to prevent it from overlapping the summary text.
rustdoc: add cli argument `--playground-url`
Add a new cli argument `--playground-url` for rustdoc:
`rustdoc lib.rs --playground-url="https://play.rust-lang.org/"`
`rustdoc book.md --playground-url="https://play.rust-lang.org/"`
This makes it possible for tools like https://docs.rs to generate crate docs that can submit samples code to run at https://play.rust-lang.org, even if the crate's author *forgot* putting `#![doc(html_playground_url = "https://play.rust-lang.org/")]` to crate root. By the way, I'd like to say, many crate authors are not aware of existing of `#![doc(html_playground_url = "https://play.rust-lang.org/")]`.
`--playground-url` may be reset by `--markdown-playground-url` or `#![doc(html_playground_url=...)]`, so it's backward compatible.
@alexcrichton since you implemented playground-url related features.
rustdoc: Fix some local inlining issues
* Only inline public items when inlining glob imports.
* Never inline while in a private module or a child of a private module.
* Never inline impls. This allowed the removal of a workaround in the
rendering code.
* Only inline public items when inlining glob imports.
* Never inline while in a private module or a child of a private module.
* Never inline impls. This allowed the removal of a workaround in the
rendering code.
rustdoc: fold fields for enum struct variants into a docblock
Per discussion in #37500, this PR updates the enum rendering code to wrap variants with named struct fields in a `docblock` span that is hidden automatically upon load of the page. This gives struct variant fields a clean separation from other enum variants, giving a boost to the readability of such documentation. Preview output is available [on the issue page](https://github.com/rust-lang/rust/issues/37500#issuecomment-260069269), but for the sake of completeness I'll include the images here again.
When you initially load the page, there's a line under variants with struct fields letting you know you can click to expand the listing.
If you click to expand, the header and table unfold into a nicely-indented listing.
If you want to take a look in your own browser and screen size, [I've got this version hosted on my server](https://shiva.icesoldier.me/doctest/doctest/enum.OldTopicRemoval.html).
Fixes#37500
r? @GuillaumeGomez
rustdoc: add line breaks to where clauses a la rustfmt
Much like my last PR for rustdoc (#36679), this adds line breaks to certain statements based on their line length. Here the focus was on where clauses.
Some examples:
- [Where clause in a trait function](https://shiva.icesoldier.me/custom-std/std/iter/trait.Iterator.html?search=#method.unzip) (also in the trait header block at the top of the page)
- [Where clause on a bare function](https://shiva.icesoldier.me/doc-custom2/petgraph/visit/fn.depth_first_search.html)
- [Where clauses in trait impls on a struct](https://shiva.icesoldier.me/custom-std/std/collections/struct.HashMap.html) (scroll to the bottom) These are regularly not on their own line, but will be given their own line now if their "prefix text" doesn't give them enough room to sensibly print their constraints. HashMap's trait impls provide some examples of both behaviors.
The libstd links above are the whole docs rendered with this, and the "bare function" link above is in another set that pulls some notable crates together. `petgraph` was the one that brought this request up, and that collection also includes [itertools](https://shiva.icesoldier.me/doc-custom2/itertools/trait.Itertools.html) which provided an easy sample to test with.
r? @GuillaumeGomez
rustdoc: mark unsafe fns in module page with superscript icons
Note: I'v changed the mark style. Now use superscript ⚠(U+26A0) (the old one is '[Unsafe]' literal).
Basically per https://botbot.me/mozilla/rust-docs/2016-10-19/?msg=75112017&page=1
Replace FNV with a faster hash function.
Hash table lookups are very hot in rustc profiles and the time taken within `FnvHash` itself is a big part of that. Although FNV is a simple hash, it processes its input one byte at a time. In contrast, Firefox has a homespun hash function that is also simple but works on multiple bytes at a time. So I tried it out and the results are compelling:
```
futures-rs-test 4.326s vs 4.212s --> 1.027x faster (variance: 1.001x, 1.007x)
helloworld 0.233s vs 0.232s --> 1.004x faster (variance: 1.037x, 1.016x)
html5ever-2016- 5.397s vs 5.210s --> 1.036x faster (variance: 1.009x, 1.006x)
hyper.0.5.0 5.018s vs 4.905s --> 1.023x faster (variance: 1.007x, 1.006x)
inflate-0.1.0 4.889s vs 4.872s --> 1.004x faster (variance: 1.012x, 1.007x)
issue-32062-equ 0.347s vs 0.335s --> 1.035x faster (variance: 1.033x, 1.019x)
issue-32278-big 1.717s vs 1.622s --> 1.059x faster (variance: 1.027x, 1.028x)
jld-day15-parse 1.537s vs 1.459s --> 1.054x faster (variance: 1.005x, 1.003x)
piston-image-0. 11.863s vs 11.482s --> 1.033x faster (variance: 1.060x, 1.002x)
regex.0.1.30 2.517s vs 2.453s --> 1.026x faster (variance: 1.011x, 1.013x)
rust-encoding-0 2.080s vs 2.047s --> 1.016x faster (variance: 1.005x, 1.005x)
syntex-0.42.2 32.268s vs 31.275s --> 1.032x faster (variance: 1.014x, 1.022x)
syntex-0.42.2-i 17.629s vs 16.559s --> 1.065x faster (variance: 1.013x, 1.021x)
```
(That's a stage1 compiler doing debug builds. Results for a stage2 compiler are similar.)
The attached commit is not in a state suitable for landing because I changed the implementation of FnvHasher without changing its name (because that would have required touching many lines in the compiler). Nonetheless, it is a good place to start discussions.
Profiles show very clearly that this new hash function is a lot faster to compute than FNV. The quality of the new hash function is less clear -- it seems to do better in some cases and worse in others (judging by the number of instructions executed in `Hash{Map,Set}::get`).
CC @brson, @arthurprs
Most of the Rust community agrees that the vec! macro is clearer when
called using square brackets [] instead of regular brackets (). Most of
these ocurrences are from before macros allowed using different types of
brackets.
There is one left unchanged in a pretty-print test, as the pretty
printer still wants it to have regular brackets.
rustdoc: print non-self arguments of bare functions and struct methods on their own line
This change alters the formatting rustdoc uses when it creates function and struct method documentation. For bare functions, each argument is printed on its own line. For struct methods, non-self arguments are printed on their own line. In both cases, no line breaks are introduced if there are no arguments, and for struct methods, no line breaks are introduced if there is only a single self argument. This should aid readability of long function signatures and allow for greater comprehension of these functions.
I've run rustdoc with these changes on my crate egg-mode and its set of dependencies and put the result [on my server](https://shiva.icesoldier.me/doc-custom/egg_mode/). Of note, here are a few shortcut links that highlight the changes:
* [Bare function with a long signature](https://shiva.icesoldier.me/doc-custom/egg_mode/place/fn.reverse_geocode.html)
* [Struct methods, with single self argument and with self and non-self arguments](https://shiva.icesoldier.me/doc-custom/egg_mode/tweet/struct.Timeline.html#method.reset)
* [Bare functions with no arguments](https://shiva.icesoldier.me/doc-custom/rand/fn.thread_rng.html) and [struct methods with no arguments](https://shiva.icesoldier.me/doc-custom/hyper/client/struct.Client.html#method.new) are left unchanged.
This PR consists of two commits: one for bare functions and one for struct methods.
* ignore signatures 80 characters or shorter
* otherwise, put arguments and return arrow on their own line, indented
to the opening parenthesis
in doing this, most of a plain-text output has been written for rustdoc,
accessible through "alternate" Display printing: "{:#}"
Set run button transparent instead of invisible
r? @steveklabnik
And of course a screenshot:
rustdoc: Don't add extra newlines for fully opaque structs
Changes the definition for braced structs with only private or hidden fields to save space on the page.
Before:
```
pub struct Vec<T> {
// some fields omitted
}
```
After:
```
pub struct Vec<T> { /* fields omitted */ }
```
This also cleans up empty braced structs.
Before:
```
pub struct Foo {
}
```
After:
```
pub struct Foo {}
```
[before](https://doc.rust-lang.org/nightly/std/vec/struct.Vec.html) [after](https://ollie27.github.io/rust_doc_test/std/vec/struct.Vec.html)
cc #34713
Changes the definition for opaque structs to look like `pub struct Vec<T>
{ /* fields omitted */ }` to save space on the page.
Also only use one line for empty braced structs.
