Document other kinds of unstability in The Unstable Book #41142

frewsxcv · 2017-04-07T14:47:00Z

Right now, The Unstable Book is just a list of unstable lang/lib features. There are other things like compiler flags which are also considered unstable that should be documented in The Unstable Book. This requires adjusting the tidy lint a bit to accommodate other sections. Right now I'm thinking that all sections (features, flags, etc) will live in their own subdirectory.

frewsxcv · 2017-04-07T14:47:44Z

Relevant thread: #40018 (comment)

frewsxcv · 2017-04-07T15:56:42Z

Reminder for future self: remove this hack e280515

brson · 2017-04-08T00:07:06Z

This may not be the issue, but there are a number of stable features that are actually just "stable", like target specs and llvm plugins, where we don't even try to maintain stability. It would be nice to have a discussion of those somewhere.

frewsxcv · 2017-04-09T19:36:43Z

I'm waiting on #40018 to merge before I work on this.

frewsxcv · 2017-04-14T03:02:47Z

Copying @est31's text from #41289:

I think for greater categorisation, the unstable book should be divided into sections.

A proposal:

Compiler internal lang features ("not intended for general use")

Permanently unstable features that are not compiler internal (like the llvm intrinsics)

Novel lang features (with intent to stabilize them some day)

Library features

??

Some sections should have a higher standard of documentation, like the novel lang features, others like the library features already have documentation in rustdoc (see #41288), so their documentation should be limited to a link to the tracking issue (and maybe their rustdoc), and the "not intended for general use" features can get a lower priority to be documented as well.

Prior to this commit, the contents of the Unstable Book were assumed to be unstable features. This commit moves features into 'language features' or 'library features' subsections. It also moves the 'linker_flavor' compiler flag into a new 'Compiler Flags' subsection. Even though it was helpful, I removed the tidy check that cross-references the SUMMARY.md links with the Unstable Book directory contents just because it would be difficult to maintain. Relevant PR: rust-lang#41142.

…teveklabnik Add top level sections to the Unstable Book. Prior to this commit, the contents of the Unstable Book were assumed to be unstable features. This commit moves features into 'language features' or 'library features' subsections. It also moves the 'linker_flavor' compiler flag into a new 'Compiler Flags' subsection. Even though it was helpful, I removed the tidy check that cross-references the SUMMARY.md links with the Unstable Book directory contents just because it would be difficult to maintain. Relevant PR: rust-lang#41142.

Prior to this commit, the contents of the Unstable Book were assumed to be unstable features. This commit moves features into 'language features' or 'library features' subsections. It also moves the 'linker_flavor' compiler flag into a new 'Compiler Flags' subsection. Even though it was helpful, I removed the tidy check that cross-references the SUMMARY.md links with the Unstable Book directory contents just because it would be difficult to maintain. Relevant PR: rust-lang#41142.

…teveklabnik Add top level sections to the Unstable Book. Prior to this commit, the contents of the Unstable Book were assumed to be unstable features. This commit moves features into 'language features' or 'library features' subsections. It also moves the 'linker_flavor' compiler flag into a new 'Compiler Flags' subsection. Even though it was helpful, I removed the tidy check that cross-references the SUMMARY.md links with the Unstable Book directory contents just because it would be difficult to maintain. Relevant PR: rust-lang#41142.

frewsxcv · 2017-04-20T04:38:55Z

This was partially completed in #41295.

steveklabnik · 2017-04-25T08:15:39Z

In #41288 @est31 suggests that we should keep the library features minimal; I agree. They should exist, so you can see everything that's unstable, but there's no reason to duplicate their docs.

steveklabnik · 2017-08-30T19:39:45Z

19:39 < frewsxcv> i think the main thing missing for this is all the unstable
                  command line options

frewsxcv · 2017-09-16T21:59:18Z

regarding unsafe command line options, one can see them via rustc -Z help. it looks like the options are all defined in this src/librustc/session/config.rs file. they seem to all be exposed on rustc::session::Session and rustc::session::config::DebuggingOptions. seems like we should be able to autogenerate all the unsafe command line options pages like we do for the other unstable book sections (via src/tools/unstable-book-gen)

steveklabnik · 2019-01-08T20:15:45Z

Triage: we now have https://doc.rust-lang.org/rustc/command-line-arguments.html, but it doesn't talk about -Z.

DevQps · 2019-04-03T10:05:45Z

I just saw that the Unstable Book already contains a list of unstable compiler flags here which I guess means that this issue is already solved right?

Maybe we should create a separate issue for the missing -Z description in https://doc.rust-lang.org/rustc/command-line-arguments.html and close this one? Maybe also create a separate issue to autogenerate the unsafe nightly commands for the Unstable Book. That way we can keep the tasks that need to be done clearly isolated.

@steveklabnik If you agree I can create these new issues with a nice description of what needs to be done!

steveklabnik · 2019-04-03T14:49:01Z

Maybe we should create a separate issue for the missing -Z description in https://doc.rust-lang.org/rustc/command-line-arguments.html and close this one?

Yes! Alternatively, if this is something you'd like to send a PR for, we can just keep this issue open and use that PR to close it.

Maybe also create a separate issue to autogenerate the unsafe nightly commands for the Unstable Book.

I would prefer not to, I don't think this is the job for the unstable book.

DevQps · 2019-04-03T16:05:03Z

Yes! Alternatively, if this is something you'd like to send a PR for, we can just keep this issue open and use that PR to close it.
I'll go ahead and do that then!

I would prefer not to, I don't think this is the job for the unstable book.
I can understand that you have this view! I do not really have much of a view myself on this, though I do think that we should keep duplication between the rustc docs and other docs to a minimum (or to keep documentation duplication to a minimum in general because its easier to maintain). The rustc docs are probably a better place to document this.

However, this does lead me to the following question: Currently, there is already a compiler flags section in the unstable book. For example the -Z emit-stack-sizes flag. I think we should either try to complete this section or remove/move it to the rustc docs all-together. What is your opinion on this?

steveklabnik · 2019-04-03T16:28:21Z

Moving it to the rustc docs seems appropriate to me!

DevQps · 2019-04-03T20:05:01Z

Moving it to the rustc docs seems appropriate to me!

I created an issue for this here: #59679
Then we can use this issue for adding -Z to the compiler flags section!

…mertj Document the -Z flag to the rustc book # Description Changes: - Added new documentation on the `-Z` flag of rustc in the command-line arguments section of the rustc book. If I need to rephrase anything or if you have any improvements, please let me know! I deliberately did not create an exhaustive list of all options since they are likely to change over time and per toolchain version. closes rust-lang#41142

frewsxcv added the A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools label Apr 7, 2017

frewsxcv mentioned this issue Apr 14, 2017

Add top level sections to the Unstable Book. #41295

Merged

frewsxcv mentioned this issue Apr 14, 2017

Create sections inside the unstable book #41289

Closed

frewsxcv assigned steveklabnik and unassigned steveklabnik Apr 14, 2017

steveklabnik mentioned this issue Apr 25, 2017

Limit documentation of library features in the unstable book #41288

Closed

Mark-Simulacrum added the C-bug Category: This is a bug. label Jul 27, 2017

steveklabnik added the P-medium Medium priority label Aug 30, 2017

DevQps mentioned this issue Apr 3, 2019

Move the compiler flags in the unstable book to the rustc book #59679

Open

DevQps mentioned this issue Apr 3, 2019

Document the -Z flag to the rustc book #59680

Merged

bors closed this as completed in #59680 Apr 12, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document other kinds of unstability in The Unstable Book #41142

Document other kinds of unstability in The Unstable Book #41142

frewsxcv commented Apr 7, 2017

frewsxcv commented Apr 7, 2017

frewsxcv commented Apr 7, 2017

brson commented Apr 8, 2017

frewsxcv commented Apr 9, 2017

frewsxcv commented Apr 14, 2017

frewsxcv commented Apr 20, 2017

steveklabnik commented Apr 25, 2017

steveklabnik commented Aug 30, 2017

frewsxcv commented Sep 16, 2017

steveklabnik commented Jan 8, 2019

DevQps commented Apr 3, 2019

steveklabnik commented Apr 3, 2019

DevQps commented Apr 3, 2019

steveklabnik commented Apr 3, 2019

DevQps commented Apr 3, 2019

Document other kinds of unstability in The Unstable Book #41142

Document other kinds of unstability in The Unstable Book #41142

Comments

frewsxcv commented Apr 7, 2017

frewsxcv commented Apr 7, 2017

frewsxcv commented Apr 7, 2017

brson commented Apr 8, 2017

frewsxcv commented Apr 9, 2017

frewsxcv commented Apr 14, 2017

frewsxcv commented Apr 20, 2017

steveklabnik commented Apr 25, 2017

steveklabnik commented Aug 30, 2017

frewsxcv commented Sep 16, 2017

steveklabnik commented Jan 8, 2019

DevQps commented Apr 3, 2019

steveklabnik commented Apr 3, 2019

DevQps commented Apr 3, 2019

steveklabnik commented Apr 3, 2019

DevQps commented Apr 3, 2019