rustdoc: Display "private fields" instead of "fields omitted" #92699
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Also:
* Always use `/* */` block comments
* Use the same message everywhere, rather than sometimes prefixing
with "some"
When I first read rustdoc docs, I was confused why the fields were being
omitted. It was only later that I realized it was because they were
private. It's also always bothered me that rustdoc sometimes uses `//`
and sometimes uses `/*` comments for these messages, so this change
makes them all use `/*`.
Technically, I think fields can be omitted if they are public but
`doc(hidden)` too, but `doc(hidden)` is analogous to privacy. It's
really just used to emulate "doc privacy" when -- because of technical
limitations -- an item has to be public. So I think it's fine to include
this under the category of "private fields".
rustbot
added
the
T-rustdoc
rust-highfive
added
the
S-waiting-on-review
Before/After ScreenshotsBefore
After
Before
After
Before
After
|
|
Great idea, thanks for pursuing this. To briefly bikeshed: what do you
think of saying "all fields private," and "some fields private" when
appropriate? It seems slightly clearer to me, though the version in this PR
is also a nice improvement.
|
|
I kind of like the simplicity of just |
|
Nah, let's go ahead with "private fields." @bors r+ rollup |
|
📌 Commit 2b70a3d has been approved by |
bors
added
S-waiting-on-bors
|
Just so you know, this is what it looks like when only some fields are private:
|
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
Jan 11, 2022
rustdoc: Display "private fields" instead of "fields omitted"
Also:
* Always use `/* */` block comments
* Use the same message everywhere, rather than sometimes prefixing
with "some"
When I first read rustdoc docs, I was confused why the fields were being
omitted. It was only later that I realized it was because they were
private. It's also always bothered me that rustdoc sometimes uses `//`
and sometimes uses `/*` comments for these messages, so this change
makes them all use `/*`.
Technically, I think fields can be omitted if they are public but
`doc(hidden)` too, but `doc(hidden)` is analogous to privacy. It's
really just used to emulate "doc privacy" when -- because of technical
limitations -- an item has to be public. So I think it's fine to include
this under the category of "private fields".
r? `@jsha`
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
Jan 11, 2022
rustdoc: Display "private fields" instead of "fields omitted"
Also:
* Always use `/* */` block comments
* Use the same message everywhere, rather than sometimes prefixing
with "some"
When I first read rustdoc docs, I was confused why the fields were being
omitted. It was only later that I realized it was because they were
private. It's also always bothered me that rustdoc sometimes uses `//`
and sometimes uses `/*` comments for these messages, so this change
makes them all use `/*`.
Technically, I think fields can be omitted if they are public but
`doc(hidden)` too, but `doc(hidden)` is analogous to privacy. It's
really just used to emulate "doc privacy" when -- because of technical
limitations -- an item has to be public. So I think it's fine to include
this under the category of "private fields".
r? ``@jsha``
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Jan 12, 2022
…askrgr Rollup of 14 pull requests Successful merges: - rust-lang#92328 (Tweak sentence in `transmute` docs) - rust-lang#92432 (Error when selected impl is not const in constck) - rust-lang#92506 (Document Box<T> FFI guarantee in 1.41.0 release notes) - rust-lang#92699 (rustdoc: Display "private fields" instead of "fields omitted") - rust-lang#92703 (RELEASES.md: Add 1.58 release note for `File::options` stabilization) - rust-lang#92707 (Extended the note on the use of `no_run` attribute) - rust-lang#92709 (Improve documentation for File::options to give a more likely example) - rust-lang#92720 (Fix doc formatting for time.rs) - rust-lang#92732 (Add note about upstream commit musl-patch-configure.diff is derived from) - rust-lang#92742 (Add missing suffix for sidebar-items script path) - rust-lang#92748 (Eliminate "boxed" wording in `std::error::Error` documentation) - rust-lang#92754 (Update AsmArgs field visibility for rustfmt) - rust-lang#92756 (:arrow_up: rust-analyzer) - rust-lang#92764 (Fix rust logo style) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Also:
/* */block commentswith "some"
When I first read rustdoc docs, I was confused why the fields were being
omitted. It was only later that I realized it was because they were
private. It's also always bothered me that rustdoc sometimes uses
//and sometimes uses
/*comments for these messages, so this changemakes them all use
/*.Technically, I think fields can be omitted if they are public but
doc(hidden)too, butdoc(hidden)is analogous to privacy. It'sreally just used to emulate "doc privacy" when -- because of technical
limitations -- an item has to be public. So I think it's fine to include
this under the category of "private fields".
r? @jsha