Expose all OS-specific modules in libstd doc.
1. Uses the special `--cfg dox` configuration passed by rustbuild when running `rustdoc`. Changes the `#[cfg(platform)]` into `#[cfg(any(dox, platform))]` so that platform-specific API are visible to rustdoc.
2. Since platform-specific implementations often won't compile correctly on other platforms, `rustdoc` is changed to apply `everybody_loops` to the functions during documentation and doc-test harness.
3. Since platform-specific code are documented on all platforms now, it could confuse users who found a useful API but is non-portable. Also, their examples will be doc-tested, so must be excluded when not testing on the native platform. An undocumented attribute `#[doc(cfg(...))]` is introduced to serve the above purposed.
Fixes#24658 (Does _not_ fully implement #1998).
This attribute has two effects:
1. Items with this attribute and their children will have the "This is
supported on **** only" message attached in the documentation.
2. The items' doc tests will be skipped if the configuration does not
match.
rustdoc: print associated types in traits "implementors" section
When viewing a trait's implementors, they won't show anything about the implementation other than any bounds on the generics. You can see the full implementation details on the page for the type, but if the type is external (e.g. it's an extension trait being implemented for primitives), then you'll never be able to see the details of the implementation without opening the source code. This doesn't solve everything about that, but it does still show an incredibly useful piece of information: the associated types. This can help immensely for traits like `Deref` or `IntoIterator` in libstd, and also for traits like `IntoFuture` outside the standard library.
Fixes#24200🚨 BIKESHED ALERT 🚨 The indentation and sizing of the types is suspect. I put it in the small text so it wouldn't blend in with the next impl line. (It shares a CSS class with the where clauses, as you can see in the following image.) However, the indentation is nonstandard. I initially tried with no indentation (looked awkward and blended too well with the surrounding impls) and with 4-space indentation (too easy to confuse with where clauses), before settling on the 2-space indentation seen below. It's... okay, i guess. Open to suggestions.
rustdoc: add [src] links to associated functions inside an impl block
While impl blocks currently have a `[src]` link to show the source for the impl block as a whole, individual methods inside that impl block do not. This can pose a problem for structs with a lot of methods, like many in libstd. This change adds little `[src]` links to individual methods that point directly to the function in the bundled source.
fixes#12932
The sidebar already has links to these h2's ids, but for convenience,
the h2 itself should also be a link (retaining its present appearance).
This should address most of #24484.
* Make sure private consts are stripped.
* Don't show a code block for the value if there is none.
* Make sure default values are shown in impls.
* Make sure docs from the trait are used if the impl has no docs.
rustdoc: Stop stripping empty modules
There is no good reason to strip empty modules with no documentation and
doing so causes subtle problems.
Fixes#42590
Currently rustdoc will fail if passed `-o foo/doc` if the `foo`
directory doesn't exist.
Also remove unneeded `mkdir` as `create_dir_all` can now handle
concurrent invocations.
This improves #32077, but is not a complete fix. For a type alias `type
NewType = AliasedType`, it will include any `impl NewType` and `impl
Trait for NewType` blocks in the documentation for `NewType`.
A complete fix would include the implementations from the aliased type
in the type alias' documentation, so that users have a complete
picture of methods that are available on the alias. However, to do this
properly would require a fix for #14072, as the alias may affect the
type parameters of the type alias, making the documentation difficult to
understand. (That is, for `type Result = std::result::Result<(), ()>` we
would ideally show documentation for `impl Result<(), ()>`, rather than
generic documentation for `impl<T, E> Result<T, E>`).
I think this improvement is worthwhile, as it exposes implementations
which are not currently documented by rustdoc. The documentation for the
implementations on the aliased type are still accessible by clicking
through to the docs for that type. (Although perhaps it's now less
obvious to the user that they should click-through to get there).
These methods can never be called through deref so there is no point
including them. For example you can't call `into_boxed_bytes` or
`into_string` on `String`.
Rather than (ab)using Debug for outputting the type in plain text use the
alternate format parameter which already does exactly that. This fixes
type parameters for example which would output raw HTML.
Also cleans up adding parens around references to trait objects.
rustdoc: add a list of headings to the sidebar
It's another misdreavus rustdoc PR, which means it's time for Bikeshed City once again! `:3`
In an effort to aid navigation in long documentation pages, this PR adds a listing of headings to the sidebars of pages where such headings exist. For example, for structs, links to their fields, inherent methods, and trait implementations are available where applicable.
Examples:
* Modules/Crate roots
* Enums
* Primitives
* Traits
* Structs
Open questions:
* Right now, these kinds of pages (and also unions) are the only pages that will receive the name header - pages for functions, constants, macros, etc, won't have the corresponding name in their sidebar. Should I print the name regardless and only add table-of-contents links for pages that have them? This would make them match, for example, a struct with no public fields, no methods, and no trait implementations. The latter would still have a "Struct MyStruct" line above the module contents, with no header links to speak of, whereas a function wouldn't even have "Function my\_function".
* This is only a header listing, but there has been requests to include a more-complete listing of fields/methods/traits/etc, for example in #41123.
Instead of rendering all of the HTML in rustdoc this relies on
pulldown-cmark's `push_html` to do most of the work. A few iterator
adapters are used to make rustdoc specific modifications to the output.
This also fixes MarkdownHtml and link titles in plain_summary_line.
Fix for #39596: sort Trait2 before Trait10.
This is a change discussed in #39596. Essentially, item names will be sorted as if they're (&str, u64) pairs instead of just `&str`, meaning that `"Apple" < "Banana"` and also `"Fruit10" > "Fruit2"`.
Sample sorting:
1. Apple
2. Banana
3. Fruit
4. Fruit0
5. Fruit00
6. Fruit1
7. Fruit01
8. Fruit2
9. Fruit02
10. Fruit20
11. Fruit100
12. Pear
Examples of generated documentation:
https://docs.charr.xyz/before-doc/test_sorting/https://docs.charr.xyz/after-doc/test_sorting/
Screenshots of generated documentation:
Before: http://imgur.com/Ktb10ti
After: http://imgur.com/CZJjqIN
