Start documenting rustc

[mrhota]

As far as I know, we don't have any reference documentation on the actual tools in the rust tool suite.

[matthewjasper]

Is this supposed to be part of a separate PR?

[mrhota]

no: that feature is already documented here, so I'm just cleaning this list up.

[matthewjasper]

You can just link to ../rustdoc/index.html for documenting rustdoc (and ../cargo/index.html for cargo)

[mrhota]

oh dang it, I didn't even know about those. I'll link to the references.

[Havvy]

We don't document nightly-only features in the Reference, to avoid having too large of a moving target to follow. Instead, said nightly features should be documented in the Unsafe Book inside the rust-lang/rust repo.

[mrhota]

I know, but the problem is rustup run stable rustc -C help says you can use s and z opt-levels. I thought it was worth mentioning you can't use those on non-nightlies.

I'm not married to the wording, obviously 😃

[mrhota]

I created rust-lang/rust#47651 for making non-nightlies stop reporting s and z options.

[Havvy]

This is an extension to the scope of the Reference, and as such, needs to be discussed during a documentation meeting. As such, I've added it to the agenda for the next one on Tuesday, January 23rd. Anybody interested is free to attend (like all documentation meetings). They're in #rust-docs on irc.mozilla.org

[steveklabnik]

Rustdoc has an entire book in src/doc, the compiler does not yet.

[steveklabnik]

So! @mrhota i want to start off by saying that doing this is awesome, however, i don't think it's appropriate for the reference. Right now, we have two out of the three, but elsewhere:

• https://doc.rust-lang.org/cargo / https://github.com/rust-lang/cargo/blob/master/src/doc (included in the rust repo via submodule)
• https://doc.rust-lang.org/rustdoc/ / https://github.com/rust-lang/rust/tree/master/src/doc/rustdoc

As for rustc, there's also an effort to make a book that's not about using, but contributing to, the compiler. I've opened a comment there to ask about this: https://internals.rust-lang.org/t/so-you-want-to-hack-on-the-rust-compiler-a-plan-for-a-book/6497/37

So, let's:

1. see what they say on internals
2. create a new book in the rust repo for rustc usage
3. improve those existing books instead of doing it here

Thank you! Let me know if you want to help with 2, we can start that in a PR before the full discussion gets going.