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

Revamp rustdoc docs about documentation using cfg #76855

Merged
merged 1 commit into from
Oct 6, 2020
Merged

Revamp rustdoc docs about documentation using cfg #76855

merged 1 commit into from
Oct 6, 2020

Conversation

jyn514
Copy link
Member

@jyn514 jyn514 commented Sep 17, 2020 •
edited
Loading

  • 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

@jyn514 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 rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Sep 17, 2020
@jyn514 jyn514 mentioned this pull request Sep 17, 2020
Closed
@ollie27
Copy link
Member

ollie27 commented Sep 18, 2020 •
edited
Loading 

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

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

@jyn514
Copy link
Member Author

jyn514 commented Sep 18, 2020

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
Copy link
Member

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
Copy link
Member Author

jyn514 commented Sep 18, 2020

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

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

jyn514 commented Sep 27, 2020

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

ollie27
ollie27 reviewed Sep 28, 2020
View reviewed changes
src/doc/rustdoc/src/advanced-features.md Outdated Show resolved Hide resolved
src/doc/rustdoc/src/advanced-features.md Outdated Show resolved Hide resolved
src/doc/rustdoc/src/advanced-features.md Outdated Show resolved Hide resolved
src/doc/rustdoc/src/unstable-features.md Outdated Show resolved Hide resolved
@ollie27 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 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
jyn514 commented Sep 28, 2020
View reviewed changes
src/doc/rustdoc/src/unstable-features.md
@@ -100,28 +100,16 @@ Note: Because of how `macro_rules` macros are scoped in Rust, the intra-doc link
These features operate by extending the `#[doc]` attribute, and thus can be caught by the compiler
and enabled with a `#![feature(...)]` attribute in your crate.

### Documenting platform-/feature-specific information
### `#[doc(cfg)]`: Recording what platforms or features are required for code to be present
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'm not super happy with this wording, but I'm not sure how better to say it.

Copy link
Contributor

Choose a reason for hiding this comment

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

Conditional documentation?

Copy link
Member Author

@jyn514 jyn514 Sep 28, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

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

@jyn514
Copy link
Member Author

jyn514 commented Oct 3, 2020

r? @ollie27

@rust-highfive rust-highfive assigned ollie27 and unassigned steveklabnik Oct 3, 2020
ollie27
ollie27 reviewed Oct 5, 2020
View reviewed changes
Copy link
Member

@ollie27 ollie27 left a comment

Choose a reason for hiding this comment

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

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

src/doc/rustdoc/src/advanced-features.md Outdated Show resolved Hide resolved
@ollie27 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
Revamp rustdoc docs about documentation using cfg
dc5a000 
- 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
Copy link
Member Author

jyn514 commented Oct 5, 2020

@bors r=ollie27 rollup

@bors
Copy link
Contributor

bors commented Oct 5, 2020

📌 Commit dc5a000 has been approved by ollie27

@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-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Oct 5, 2020
@JohnTitor JohnTitor mentioned this pull request Oct 6, 2020
Merged
bors added a commit to rust-lang-ci/rust that referenced this pull request Oct 6, 2020
@bors
Auto merge of rust-lang#77606 - JohnTitor:rollup-7rgahdt, r=JohnTitor
5ded394 
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`
@bors bors merged commit 97ee62c into rust-lang:master Oct 6, 2020
@rustbot rustbot added this to the 1.49.0 milestone Oct 6, 2020
@jyn514 jyn514 deleted the platform-specific branch February 25, 2023 18:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ollie27 ollie27 ollie27 left review comments

@pickfire pickfire pickfire left review comments

@steveklabnik steveklabnik steveklabnik approved these changes

Assignees

@ollie27 ollie27

Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
1.49.0
Development

Successfully merging this pull request may close these issues.
7 participants
@jyn514 @ollie27 @steveklabnik @bors @pickfire @rust-highfive @rustbot