It had been a source of huge bloat in rustdoc outputs. Of course, we can simply disable compiler docs (as `rustc` generates over 90M of HTML) but this approach fares better even after such decision.
Each directory now has `sidebar-items.js`, which immediately calls `initSidebarItems` with a JSON sidebar data. This file is shared throughout every item in the sidebar. The current item is highlighted via a separate JS snippet (`window.sidebarCurrent`). The JS file is designed to be loaded asynchronously, as the sidebar is rendered before the content and slow sidebar loading blocks the entire rendering. For the minimal accessibility without JS, links to the parent items are left in HTML.
In the future, it might also be possible to integrate crates data with the same fashion: `sidebar-items.js` at the root path will do that. (Currently rustdoc skips writing JS in that case.)
This has a huge impact on the size of rustdoc outputs. Originally it was 326MB uncompressed (37.7MB gzipped, 6.1MB xz compressed); it is 169MB uncompressed (11.9MB gzipped, 5.9MB xz compressed) now. The sidebar JS only takes 10MB uncompressed & 0.3MB gzipped.
The two main sub-modules, `c_str` and `os_str`, have now had some time to bake
in the standard library. This commits performs a sweep over the modules adding
various stability tags.
The following APIs are now marked `#[stable]`
* `OsString`
* `OsStr`
* `OsString::from_string`
* `OsString::from_str`
* `OsString::new`
* `OsString::into_string`
* `OsString::push` (renamed from `push_os_str`, added an `AsOsStr` bound)
* various trait implementations for `OsString`
* `OsStr::from_str`
* `OsStr::to_str`
* `OsStr::to_string_lossy`
* `OsStr::to_os_string`
* various trait implementations for `OsStr`
* `CString`
* `CStr`
* `NulError`
* `CString::new` - this API's implementation may change as a result of
rust-lang/rfcs#912 but the usage of `CString::new(thing)` looks like it is
unlikely to change. Additionally, the `IntoBytes` bound is also likely to
change but the set of implementors for the trait will not change (despite the
trait perhaps being renamed).
* `CString::from_vec_unchecked`
* `CString::as_bytes`
* `CString::as_bytes_with_nul`
* `NulError::nul_position`
* `NulError::into_vec`
* `CStr::from_ptr`
* `CStr::as_ptr`
* `CStr::to_bytes`
* `CStr::to_bytes_with_nul`
* various trait implementations for `CStr`
The following APIs remain `#[unstable]`
* `OsStr*Ext` traits remain unstable as the organization of `os::platform` is
uncertain still and the traits may change location.
* `AsOsStr` remains unstable as generic conversion traits are likely to be
rethought soon.
The following APIs were deprecated
* `OsString::push_os_str` is now called `push` and takes `T: AsOsStr` instead (a
superset of the previous functionality).
It had been a source of huge bloat in rustdoc outputs. Of course,
we can simply disable compiler docs (as `rustc` generates over 90M
of HTML) but this approach fares better even after such decision.
Each directory now has `sidebar-items.js`, which immediately calls
`initSidebarItems` with a JSON sidebar data. This file is shared
throughout every item in the sidebar. The current item is
highlighted via a separate JS snippet (`window.sidebarCurrent`).
The JS file is designed to be loaded asynchronously, as the sidebar
is rendered before the content and slow sidebar loading blocks
the entire rendering. For the minimal accessibility without JS,
links to the parent items are left in HTML.
In the future, it might also be possible to integrate crates data
with the same fashion: `sidebar-items.js` at the root path will do
that. (Currently rustdoc skips writing JS in that case.)
This has a huge impact on the size of rustdoc outputs. Originally
it was 326MB uncompressed (37.7MB gzipped, 6.1MB xz compressed);
it is 169MB uncompressed (11.9MB gzipped, 5.9MB xz compressed) now.
The sidebar JS only takes 10MB uncompressed & 0.3MB gzipped.
This commit deprecates the majority of std::old_io::fs in favor of std::fs and
its new functionality. Some functions remain non-deprecated but are now behind a
feature gate called `old_fs`. These functions will be deprecated once
suitable replacements have been implemented.
The compiler has been migrated to new `std::fs` and `std::path` APIs where
appropriate as part of this change.
In preparation for upcoming changes to the `Writer` trait (soon to be called
`Write`) this commit renames the current `write` method to `write_all` to match
the semantics of the upcoming `write_all` method. The `write` method will be
repurposed to return a `usize` indicating how much data was written which
differs from the current `write` semantics. In order to head off as much
unintended breakage as possible, the method is being deprecated now in favor of
a new name.
[breaking-change]
This pull request add tooltips to most links of sidebar.
The tooltips display "summary line" of items' document.
Some lengthy/annoying raw markdown code are eliminated, such as links and headers.
- `[Rust](http://rust-lang.org)` displays as `Rust` (no URLs)
- `# header` displays as `header` (no `#`s)
Some inline spans, e.g. ``` `code` ``` and ```*emphasis*```, are kept as they are, for better readable.
I've make sure `&` `'` `"` `<` and `>` are properly displayed in tooltips, for example, `&'a Option<T>`.
Online preview: http://liigo.com/tmp/tooltips/std/index.html
@alexcrichton @steveklabnik since you have reviewed my previous ([v1](https://github.com/rust-lang/rust/pull/13014),[v2](https://github.com/rust-lang/rust/pull/16448)) PRs of this serise, which have been closed for technical reasons. Thank you.
This commit is an implementation of [RFC 565][rfc] which is a stabilization of
the `std::fmt` module and the implementations of various formatting traits.
Specifically, the following changes were performed:
[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/0565-show-string-guidelines.md
* The `Show` trait is now deprecated, it was renamed to `Debug`
* The `String` trait is now deprecated, it was renamed to `Display`
* Many `Debug` and `Display` implementations were audited in accordance with the
RFC and audited implementations now have the `#[stable]` attribute
* Integers and floats no longer print a suffix
* Smart pointers no longer print details that they are a smart pointer
* Paths with `Debug` are now quoted and escape characters
* The `unwrap` methods on `Result` now require `Display` instead of `Debug`
* The `Error` trait no longer has a `detail` method and now requires that
`Display` must be implemented. With the loss of `String`, this has moved into
libcore.
* `impl<E: Error> FromError<E> for Box<Error>` now exists
* `derive(Show)` has been renamed to `derive(Debug)`. This is not currently
warned about due to warnings being emitted on stage1+
While backwards compatibility is attempted to be maintained with a blanket
implementation of `Display` for the old `String` trait (and the same for
`Show`/`Debug`) this is still a breaking change due to primitives no longer
implementing `String` as well as modifications such as `unwrap` and the `Error`
trait. Most code is fairly straightforward to update with a rename or tweaks of
method calls.
[breaking-change]
Closes#21436
There's been some debate over the precise form that these APIs should take, and
they've undergone some changes recently, so these APIs are going to be left
unstable for now to be fleshed out during the next release cycle.
fmt::Show is for debugging, and can and should be implemented for
all public types. This trait is used with `{:?}` syntax. There still
exists #[derive(Show)].
fmt::String is for types that faithfully be represented as a String.
Because of this, there is no way to derive fmt::String, all
implementations must be purposeful. It is used by the default format
syntax, `{}`.
This will break most instances of `{}`, since that now requires the type
to impl fmt::String. In most cases, replacing `{}` with `{:?}` is the
correct fix. Types that were being printed specifically for users should
receive a fmt::String implementation to fix this.
Part of #20013
[breaking-change]
While talking on IRC, someone wanted to post a link to the Rust source code, but while the lines of the rendered source code do have anchors (`<span id="[line number]">`), there is no convenient way to make links as they are not clickable. This PR makes them clickable.
Also, a minor fix of the FAQ is included.
This commit is an implementation of [RFC 503][rfc] which is a stabilization
story for the prelude. Most of the RFC was directly applied, removing reexports.
Some reexports are kept around, however:
* `range` remains until range syntax has landed to reduce churn.
* `Path` and `GenericPath` remain until path reform lands. This is done to
prevent many imports of `GenericPath` which will soon be removed.
* All `io` traits remain until I/O reform lands so imports can be rewritten all
at once to `std::io::prelude::*`.
This is a breaking change because many prelude reexports have been removed, and
the RFC can be consulted for the exact list of removed reexports, as well as to
find the locations of where to import them.
[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/0503-prelude-stabilization.md
[breaking-change]
Closes#20068
This commit is an implementation of [RFC 526][rfc] which is a change to alter
the definition of the old `fmt::FormatWriter`. The new trait, renamed to
`Writer`, now only exposes one method `write_str` in order to guarantee that all
implementations of the formatting traits can only produce valid Unicode.
[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/0526-fmt-text-writer.md
One of the primary improvements of this patch is the performance of the
`.to_string()` method by avoiding an almost-always redundant UTF-8 check. This
is a breaking change due to the renaming of the trait as well as the loss of the
`write` method, but migration paths should be relatively easy:
* All usage of `write` should move to `write_str`. If truly binary data was
being written in an implementation of `Show`, then it will need to use a
different trait or an altogether different code path.
* All usage of `write!` should continue to work as-is with no modifications.
* All usage of `Show` where implementations just delegate to another should
continue to work as-is.
[breaking-change]
Closes#20352
