Revamp rustdoc docs about documentation using `cfg` by jyn514 · Pull Request #76855 · rust-lang/rust

jyn514 · 2020-09-17T22:08:25Z

Move cfg(doc) out of unstable-features. It's not unstable.
Remove outdated reference to everybody_loops.
Improve wording in various places
Give an example of code this allows (and does not allow)
Link to cfg(doc) in doc(cfg) documentation. Since one is stable
and the other is not, don't combine them.
Cleanup wording for doc(cfg)
Incorporate changes from Remove weird looking dashes #76849
Mention that doc(cfg) is also for features

Addresses #76849 (comment).
Obsoletes #76849 (I made sure to fix the weird dashes too).
r? @steveklabnik

ollie27 · 2020-09-18T01:04:50Z

* Move it out of `unstable-features`. It's not unstable.

#[doc(cfg(...))] is still unstable so why were its docs moved?

jyn514 · 2020-09-18T02:11:34Z

Hmm, you're right that doc(cfg) is unstable, but it seems like it should go near the section on cfg(doc) since they're often used together. Maybe I could say in advanced-features that doc(cfg) is unstable and have a short paragraph linking there from unstable-features?

steveklabnik · 2020-09-18T14:01:41Z

Hmm, you're right that doc(cfg) is unstable, but it seems like it should go near the section on cfg(doc) since they're often used together. Maybe I could say in advanced-features that doc(cfg) is unstable and have a short paragraph linking there from unstable-features?

Traditionally, we keep a very clean separation here; we only talk about stable things in stable docs, and unstable things in unstable docs.

However, I think the rustdoc team should document its tool the way it wants to, and this is an odd case. I'm fine with this either way.

jyn514 · 2020-09-18T14:14:25Z

Ok, I moved doc(cfg) back to unstable-features.md with a link to cfg(doc).

jyn514 · 2020-09-27T14:54:50Z

ping @ollie27 - does the new documentation look good to you?

src/doc/rustdoc/src/advanced-features.md

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

jyn514 · 2020-09-28T14:11:37Z

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

I'm not super happy with this wording, but I'm not sure how better to say it.

Conditional documentation?

No, the documentation is usually unconditional, e.g. cfg(any(doc, unix)), but the code is only present when the cfg is set.

jyn514 · 2020-10-03T17:44:11Z

r? @ollie27

src/doc/rustdoc/src/advanced-features.md

ollie27

Looks good to me. r=me with that one typo fixed and the commits squashed.

src/doc/rustdoc/src/advanced-features.md

- Move `cfg(doc)` out of `unstable-features`. It's not unstable. - Remove outdated reference to `everybody_loops`. - Improve wording in various places - Give an example of code this allows (and does not allow) - Link to `cfg(doc)` in `doc(cfg)` documentation. Since one is stable and the other is not, don't combine them. - Cleanup wording for `doc(cfg)` - Incorporate changes from rust-lang#76849 - Mention that `doc(cfg)` is also for features

jyn514 · 2020-10-05T23:08:31Z

@bors r=ollie27 rollup

bors · 2020-10-05T23:08:32Z

📌 Commit dc5a000 has been approved by ollie27

Rollup of 13 pull requests Successful merges: - rust-lang#76388 (Add a note about the panic behavior of math operations on time objects) - rust-lang#76855 (Revamp rustdoc docs about documentation using `cfg`) - rust-lang#76995 (Reduce boilerplate with the matches! macro) - rust-lang#77228 (Add missing examples for MaybeUninit) - rust-lang#77528 (Avoid unchecked casts in net parser) - rust-lang#77534 (Disallow overriding forbid in same scope) - rust-lang#77555 (Allow anyone to set regression labels) - rust-lang#77558 (Rename bootstrap/defaults/{config.toml.PROFILE => config.PROFILE.toml}) - rust-lang#77559 (Fix rustdoc warnings about invalid Rust syntax) - rust-lang#77560 (Fix LitKind's byte buffer to use refcounted slice) - rust-lang#77573 (Hint doc use convert::identity relative link) - rust-lang#77587 (Fix span for unicode escape suggestion.) - rust-lang#77591 (Record `expansion_that_defined` into crate metadata) Failed merges: r? `@ghost`

jyn514 added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools labels Sep 17, 2020

rust-highfive assigned steveklabnik Sep 17, 2020

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Sep 17, 2020

jyn514 mentioned this pull request Sep 17, 2020

Remove weird looking dashes #76849

Closed

steveklabnik approved these changes Sep 18, 2020

View reviewed changes

jyn514 force-pushed the platform-specific branch 2 times, most recently from 2787f9d to bc12abe Compare September 18, 2020 14:18

ollie27 reviewed Sep 28, 2020

View reviewed changes

ollie27 added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 28, 2020

jyn514 added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Sep 28, 2020

jyn514 commented Sep 28, 2020

View reviewed changes

rust-highfive assigned ollie27 and unassigned steveklabnik Oct 3, 2020

steveklabnik reviewed Oct 5, 2020

View reviewed changes

src/doc/rustdoc/src/advanced-features.md Outdated Show resolved Hide resolved

ollie27 reviewed Oct 5, 2020

View reviewed changes

src/doc/rustdoc/src/advanced-features.md Outdated Show resolved Hide resolved

ollie27 added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 5, 2020

jyn514 force-pushed the platform-specific branch from a3352dc to 3c7433d Compare October 5, 2020 23:01

jyn514 force-pushed the platform-specific branch from 3c7433d to dc5a000 Compare October 5, 2020 23:07

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-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Oct 5, 2020

JohnTitor mentioned this pull request Oct 6, 2020

Rollup of 13 pull requests #77606

Merged

bors merged commit 97ee62c into rust-lang:master Oct 6, 2020

rustbot added this to the 1.49.0 milestone Oct 6, 2020

jyn514 deleted the platform-specific branch February 25, 2023 18:32

Uh oh!

Conversation

jyn514 commented Sep 17, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ollie27 commented Sep 18, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jyn514 commented Sep 18, 2020

Uh oh!

steveklabnik commented Sep 18, 2020

Uh oh!

jyn514 commented Sep 18, 2020

Uh oh!

jyn514 commented Sep 27, 2020

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jyn514 Sep 28, 2020

Choose a reason for hiding this comment

Uh oh!

pickfire Sep 28, 2020

Choose a reason for hiding this comment

Uh oh!

jyn514 Sep 28, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jyn514 commented Oct 3, 2020

Uh oh!

Uh oh!

ollie27 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jyn514 commented Oct 5, 2020

Uh oh!

bors commented Oct 5, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

jyn514 commented Sep 17, 2020 •

edited

Loading

ollie27 commented Sep 18, 2020 •

edited

Loading

jyn514 Sep 28, 2020 •

edited

Loading