Skip to content

Document other kinds of unstability in The Unstable Book #41142

@frewsxcv

Description

@frewsxcv
Contributor

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.

Activity

added
A-docsArea: Documentation for any part of the project, including the compiler, standard library, and tools
on Apr 7, 2017
frewsxcv

frewsxcv commented on Apr 7, 2017

@frewsxcv
ContributorAuthor

Relevant thread: #40018 (comment)

frewsxcv

frewsxcv commented on Apr 7, 2017

@frewsxcv
ContributorAuthor

Reminder for future self: remove this hack e280515

brson

brson commented on Apr 8, 2017

@brson
Contributor

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

frewsxcv commented on Apr 9, 2017

@frewsxcv
ContributorAuthor

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

frewsxcv

frewsxcv commented on Apr 14, 2017

@frewsxcv
ContributorAuthor

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.

20 remaining items

steveklabnik

steveklabnik commented on Aug 30, 2017

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

frewsxcv commented on Sep 16, 2017

@frewsxcv
ContributorAuthor

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

steveklabnik commented on Jan 8, 2019

@steveklabnik
Contributor

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

DevQps

DevQps commented on Apr 3, 2019

@DevQps
Contributor

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

steveklabnik commented on Apr 3, 2019

@steveklabnik
Contributor

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

DevQps commented on Apr 3, 2019

@DevQps
Contributor

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

steveklabnik commented on Apr 3, 2019

@steveklabnik
Contributor

Moving it to the rustc docs seems appropriate to me!

DevQps

DevQps commented on Apr 3, 2019

@DevQps
Contributor

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!

added a commit that references this issue on Apr 11, 2019
632b11c
added a commit that references this issue on Apr 11, 2019
37cb3ee
added a commit that references this issue on Apr 12, 2019
59e95dd
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsC-bugCategory: This is a bug.P-mediumMedium priority

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      Participants

      @steveklabnik@brson@frewsxcv@Mark-Simulacrum@DevQps

      Issue actions

        Document other kinds of unstability in The Unstable Book · Issue #41142 · rust-lang/rust