Change:
It'd be helpful for people who want make documentation pull requests that aren't just typo's to be able to build the documentation, and preview it themselves. Adding a "How To" about how documentation for the main repo should be built, would be helpful.
Building the documentation should be as simple as , which however requires a full rust build which can take some time. Once a full build has been completed should allow you to build the documentation without rebuilding the whole compiler. I don't think there currently is a way to build the docs without building the compiler. Edit: Running gives a very basic introduction to rust's build system.
You can run on any crate, so I often or whatever I'm working on. It works on markdown files too.
It's worth noting that you need a (very) recent version of rustdoc to create docs from the source in master HEAD. It's often the case that even a nightly rustdoc is not new enough (although maybe it is, if you pass or something...).
Huh, I've never ran into that as an issue.

Discussion:
$ make && make install ``` <ins> ## Building Documentation If you’d like to build the documentation, it’s almost the same: ```sh ./configure $ make docs ``` Building the documentation requires building the compiler, so the above details will apply. Once you have the compiler built, you can ```sh $ make docs NO_REBUILD=1 ``` To make sure you don’t re-build the compiler because you made a change to some documentation. The generated documentation will appear in a top-level `doc` directory, created by the `make` rule. </ins> ## Notes Since the Rust compiler is written in Rust, it must be built by a

`"mips"`, `"powerpc"`, `"arm"`, or `"aarch64"`. * `target_endian = "..."`. Endianness of the target CPU, either `"little"` or `"big"`. <ins> * `target_env = ".."` - an option provided by the compiler by default describing the runtime environment of the target platform. Some examples of this are `musl` for builds targeting the MUSL libc implementation, `msvc` for Windows builds targeting MSVC, and `gnu` frequently the rest of the time. This option may also be blank on some platforms. </ins> * `target_family = "..."`. Operating system family of the target, e. g. `"unix"` or `"windows"`. The value of this configuration option is defined as a configuration itself, like `unix` or `windows`.

`panic!` is a macro, similar to `println!()` that we’ve already seen. Unlike `println!()`, `panic!()` causes the current thread of execution to crash with <del> the given message. </del> <ins> the given message. Because this function will cause a crash, it will never return, and so it has the type ‘`!`’, which is read ‘diverges’. </ins> <del> Because this function will cause a crash, it will never return, and so it has the type ‘`!`’, which is read ‘diverges’. A diverging function can be used as any type: </del> <ins> If you add a main function that calls `diverges()` and run it, you’ll get some output that looks like this: ```text thread ‘<main>’ panicked at ‘This function never returns!’, hello.rs:2 ``` If you want more information, you can get a backtrace by setting the `RUST_BACKTRACE` environment variable: ```text $ RUST_BACKTRACE=1 ./diverges thread '<main>' panicked at 'This function never returns!', hello.rs:2 stack backtrace: 1:     0x7f402773a829 - sys::backtrace::write::h0942de78b6c02817K8r 2:     0x7f402773d7fc - panicking::on_panic::h3f23f9d0b5f4c91bu9w 3:     0x7f402773960e - rt::unwind::begin_unwind_inner::h2844b8c5e81e79558Bw 4:     0x7f4027738893 - rt::unwind::begin_unwind::h4375279447423903650 5:     0x7f4027738809 - diverges::h2266b4c4b850236beaa 6:     0x7f40277389e5 - main::h19bb1149c2f00ecfBaa 7:     0x7f402773f514 - rt::unwind::try::try_fn::h13186883479104382231 8:     0x7f402773d1d8 - __rust_try 9:     0x7f402773f201 - rt::lang_start::ha172a3ce74bb453aK5w 10:     0x7f4027738a19 - main 11:     0x7f402694ab44 - __libc_start_main 12:     0x7f40277386c8 - <unknown> 13:                0x0 - <unknown> ``` `RUST_BACKTRACE` also works with Cargo’s `run` command: ```text $ RUST_BACKTRACE=1 cargo run Running `target/debug/diverges` thread '<main>' panicked at 'This function never returns!', hello.rs:2 stack backtrace: 1:     0x7f402773a829 - sys::backtrace::write::h0942de78b6c02817K8r 2:     0x7f402773d7fc - panicking::on_panic::h3f23f9d0b5f4c91bu9w 3:     0x7f402773960e - rt::unwind::begin_unwind_inner::h2844b8c5e81e79558Bw 4:     0x7f4027738893 - rt::unwind::begin_unwind::h4375279447423903650 5:     0x7f4027738809 - diverges::h2266b4c4b850236beaa 6:     0x7f40277389e5 - main::h19bb1149c2f00ecfBaa 7:     0x7f402773f514 - rt::unwind::try::try_fn::h13186883479104382231 8:     0x7f402773d1d8 - __rust_try 9:     0x7f402773f201 - rt::lang_start::ha172a3ce74bb453aK5w 10:     0x7f4027738a19 - main 11:     0x7f402694ab44 - __libc_start_main 12:     0x7f40277386c8 - <unknown> 13:                0x0 - <unknown> ``` A diverging function can be used as any type: </ins> ```should_panic # fn diverges() -> ! {

// y.method(); (y.vtable.method)(y.data); ``` <ins> ## Object Safety Not every trait can be used to make a trait object. For example, vectors implement `Clone`, but if we try to make a trait object: ```ignore let v = vec![1, 2, 3]; let o = &v as &Clone; ``` We get an error: ```text error: cannot convert to a trait object because trait `core::clone::Clone` is not object-safe [E0038] let o = &v as &Clone; ^~ note: the trait cannot require that `Self : Sized` let o = &v as &Clone; ^~ ``` The error says that `Clone` is not ‘object-safe’. Only traits that are object-safe can be made into trait objects. A trait is object-safe if both of these are true: * the trait does not require that `Self: Sized` * all of its methods are object-safe So what makes a method object-safe? Each method must require that `Self: Sized` or all of the following: * must not have any type parameters * must not use `Self` Whew! As we can see, almost all of these rules talk about `Self`. A good intuition is “except in special circumstances, if your trait’s method uses `Self`, it is not object-safe.” </ins>

//!     //                  7 //!     //          +-----------------+ //!     //          |                 | <del> //!     //          v   1        2    | </del> <ins> //!     //          v   1        2    |  2 </ins> //!     //          0 -----> 1 -----> 3 ---> 4 //!     //          |        ^        ^      ^ //!     //          |        | 1      |      |

/// A seek beyond the end of a stream is allowed, but implementation /// defined. /// <del> /// The behavior when seeking past the end of the stream is implementation /// defined. /// </del> /// If the seek operation completed successfully, /// this method returns the new position from the start of the stream. /// That position can be used later with `SeekFrom::Start`.