Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

add an "unstable features" chapter to the rustdoc book #49028

Merged
merged 20 commits into from
Mar 23, 2018
Merged

add an "unstable features" chapter to the rustdoc book #49028

merged 20 commits into from
Mar 23, 2018

Conversation

QuietMisdreavus
Copy link
Member

@QuietMisdreavus QuietMisdreavus commented Mar 14, 2018 •
edited
Loading

There are several rustdoc features that currently are undocumented, but also don't fit with the rest of the Rustdoc Book since they're also unstable. Some of these have corresponding feature gates and chapters in the Unstable Book, but many don't, and i wanted a place to talk about them officially.

Goal: talk about everything rustdoc can do that needs nightly

  • Feature gates (extensions to the doc attribute that can be caught by the compiler)
    • doc(cfg)
    • doc(masked)
    • doc(spotlight)
    • doc(include)
  • Command-line flags (features that require a CLI flag to use, where the flag itself is a -Z command or otherwise requires -Z unstable-options before rustdoc will accept it)
    • markdown-before-content/markdown-after-content
    • playground-url
    • display-warnings
    • crate-version
    • linker
    • sort-modules-by-appearance
    • themes/theme-checker
    • resource-suffix
    • -Z force-unstable-if-unmarked
  • Nightly-gated functionality (features that are gated by requiring a nightly build without needing a CLI flag or a feature gate to unlock)
    • intra-links
    • error numbers for compile_fail doctests

@rust-highfive
Copy link
Collaborator

r? @GuillaumeGomez

(rust_highfive has picked a reviewer for you, use r? to override)

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Mar 14, 2018
@QuietMisdreavus QuietMisdreavus mentioned this pull request Mar 16, 2018
Closed
@QuietMisdreavus
Copy link
Member Author

While investigating --display-warnings, i had trouble coming up with a good explanation of what it did that either didn't have a bug or wasn't possible with other flags. I wrote up my investigation in the "tracking issue" for it: #41574 (comment)

@QuietMisdreavus
Copy link
Member Author

QuietMisdreavus commented Mar 16, 2018 •
edited
Loading

I'm not sure whether to document -Z force-unstable-if-unmarked, since it's purely an implementation detail of the compiler and std. (I'm also not that certain what it does, other than "pass the same flag to rustc", but that might be explanation enough, in lieu of a proper explanation somewhere else. >_>)

Otherwise, short of a decision on --display-warnings, this is ready to go!

@rust-lang/docs Can y'all take a look at this and make sure i'm not being misleading or specifying too much?

@QuietMisdreavus QuietMisdreavus changed the title [WIP] add an "unstable features" chapter to the rustdoc book add an "unstable features" chapter to the rustdoc book Mar 16, 2018
@QuietMisdreavus
Copy link
Member Author

I've gone ahead and added sections about --display-warnings and -Z force-unstable-if-unmarked. As far as i know, this chapter is complete; please take a look!

frewsxcv
frewsxcv reviewed Mar 21, 2018
View reviewed changes
src/doc/rustdoc/src/unstable-features.md Outdated

This is used by the error index to ensure that the samples that correspond to a given error number
properly emit that error code. However, these error codes aren't guaranteed to be the only thing
that a piece of code emits from version to version, so this in unlikely to be stabilized in the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

*is unlikely

frewsxcv
frewsxcv approved these changes Mar 21, 2018
View reviewed changes
Copy link
Member

@frewsxcv frewsxcv left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is soo great, awesome work @QuietMisdreavus 🎉

src/doc/rustdoc/src/unstable-features.md Outdated
special marker attribute on them: `#[doc(spotlight)]`. This means that you could apply this
attribute to your own trait to include it in the "Important Traits" dialog in documentation.

The `#[doc(spotlight)]` attribute is controlled by a feature gate. For more information, see [its
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is controlled by a feature gate

would it be good to mention the name of the feature gate directly in this document?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think my original idea was that by linking to the Unstable Book, people could easily find the name of the feature gate that way, but it's not that much more to write it out here as well. I'll add it.

src/doc/rustdoc/src/unstable-features.md Outdated

[RFC 1990]: https://github.com/rust-lang/rfcs/pull/1990

`#[doc(include = "...")]` is currently controlled by a feature gate. For more information, see [its
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is currently controlled by a feature gate

would it be good to mention the name of the feature gate directly in this document?

@QuietMisdreavus
Copy link
Member Author

@frewsxcv What do you think of it now?

@frewsxcv
Copy link
Member

r=me if you don't have any other additions

@QuietMisdreavus
Copy link
Member Author

@bors r=frewsxcv

Nope, that's all i had! Thanks so much!

@bors
Copy link
Contributor

bors commented Mar 22, 2018

📌 Commit b996f9d has been approved by frewsxcv

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 22, 2018
@frewsxcv
Copy link
Member

@bors rollup

frewsxcv added a commit to frewsxcv/rust that referenced this pull request Mar 23, 2018
@frewsxcv
Rollup merge of rust-lang#49028 - QuietMisdreavus:the-dark-forbidden-…
832271f 
…corners-of-rustdoc, r=frewsxcv

add an "unstable features" chapter to the rustdoc book

There are several rustdoc features that currently are undocumented, but also don't fit with the rest of the Rustdoc Book since they're also unstable. Some of these have corresponding feature gates and chapters in the Unstable Book, but many don't, and i wanted a place to talk about them officially.

Goal: talk about everything rustdoc can do that needs nightly

- [x] Feature gates (extensions to the doc attribute that can be caught by the compiler)
  - [x] doc(cfg)
  - [x] doc(masked)
  - [x] doc(spotlight)
  - [x] doc(include)
- [x] Command-line flags (features that require a CLI flag to use, where the flag itself is a `-Z` command or otherwise requires `-Z unstable-options` before rustdoc will accept it)
  - [x] markdown-before-content/markdown-after-content
  - [x] playground-url
  - [x] display-warnings
  - [x] crate-version
  - [x] linker
  - [x] sort-modules-by-appearance
  - [x] themes/theme-checker
  - [x] resource-suffix
  - [x] `-Z force-unstable-if-unmarked`
- [x] Nightly-gated functionality (features that are gated by requiring a nightly build without needing a CLI flag or a feature gate to unlock)
  - [x] intra-links
  - [x] error numbers for `compile_fail` doctests
@frewsxcv frewsxcv mentioned this pull request Mar 23, 2018
Closed
@alexcrichton alexcrichton mentioned this pull request Mar 23, 2018
Merged
alexcrichton added a commit to alexcrichton/rust that referenced this pull request Mar 23, 2018
@alexcrichton
Rollup merge of rust-lang#49028 - QuietMisdreavus:the-dark-forbidden-…
f74d01c 
…corners-of-rustdoc, r=frewsxcv

add an "unstable features" chapter to the rustdoc book

There are several rustdoc features that currently are undocumented, but also don't fit with the rest of the Rustdoc Book since they're also unstable. Some of these have corresponding feature gates and chapters in the Unstable Book, but many don't, and i wanted a place to talk about them officially.

Goal: talk about everything rustdoc can do that needs nightly

- [x] Feature gates (extensions to the doc attribute that can be caught by the compiler)
  - [x] doc(cfg)
  - [x] doc(masked)
  - [x] doc(spotlight)
  - [x] doc(include)
- [x] Command-line flags (features that require a CLI flag to use, where the flag itself is a `-Z` command or otherwise requires `-Z unstable-options` before rustdoc will accept it)
  - [x] markdown-before-content/markdown-after-content
  - [x] playground-url
  - [x] display-warnings
  - [x] crate-version
  - [x] linker
  - [x] sort-modules-by-appearance
  - [x] themes/theme-checker
  - [x] resource-suffix
  - [x] `-Z force-unstable-if-unmarked`
- [x] Nightly-gated functionality (features that are gated by requiring a nightly build without needing a CLI flag or a feature gate to unlock)
  - [x] intra-links
  - [x] error numbers for `compile_fail` doctests
bors added a commit that referenced this pull request Mar 23, 2018
@bors
Auto merge of #49308 - alexcrichton:rollup, r=alexcrichton
c08480f 
Rollup of 15 pull requests

- Successful merges: #48265, #48528, #48552, #48624, #48883, #48909, #49028, #49030, #49102, #49160, #49169, #49203, #49262, #49272, #49295
- Failed merges: #48942, #49035
@alexcrichton alexcrichton merged commit b996f9d into rust-lang:master Mar 23, 2018
@QuietMisdreavus QuietMisdreavus deleted the the-dark-forbidden-corners-of-rustdoc branch May 9, 2018 21:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@frewsxcv frewsxcv frewsxcv approved these changes

Assignees

@GuillaumeGomez GuillaumeGomez

Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
6 participants
@QuietMisdreavus @rust-highfive @frewsxcv @bors @alexcrichton @GuillaumeGomez