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.

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

Distinguish between private items and hidden items in rustdoc #67875

Merged
merged 1 commit into from Jan 8, 2020

Conversation

@dtolnay
Copy link
Member

dtolnay commented Jan 4, 2020

I believe rustdoc should not be conflating private items (visibility lower than pub) and hidden items (attribute doc(hidden)). This matters now that Cargo is passing --document-private-items by default for bin crates. In bin crates that rely on macros, intentionally hidden implementation details of the macros can overwhelm the actual useful internal API that one would want to document.

This PR restores the strip-hidden pass when documenting private items, and introduces a separate unstable --document-hidden-items option to skip the strip-hidden pass. The two options are orthogonal to one another.

Fixes #67851. Closes #60884.

I believe rustdoc should not be conflating private items (visibility
lower than `pub`) and hidden items (attribute `doc(hidden)`). This
matters now that Cargo is passing --document-private-items by default
for bin crates. In bin crates that rely on macros, intentionally hidden
implementation details of the macros can overwhelm the actual useful
internal API that one would want to document.

This PR restores the strip-hidden pass when documenting private items,
and introduces a separate unstable --document-hidden-items option to
skip the strip-hidden pass. The two options are orthogonal to one
another.
@dtolnay

This comment has been minimized.

Copy link
Member Author

dtolnay commented Jan 4, 2020

Reassigning since QuietMisdreavus's status is "taking a break" and it looks like the recent PRs assigned to her in https://github.com/rust-lang/rust/pulls?q=is%3Apr+assignee%3AQuietMisdreavus+is%3Aclosed have all been reviewed by other people.

r? @GuillaumeGomez @ollie27

@GuillaumeGomez

This comment has been minimized.

Copy link
Member

GuillaumeGomez commented Jan 6, 2020

Looks good to me, just a question: why moving src/test/rustdoc/issue-46380.rs into a new one?

@dtolnay

This comment has been minimized.

Copy link
Member Author

dtolnay commented Jan 6, 2020

It is not moved, it is deleted because I am intentionally overruling the decision from #46412. The old test was asserting @​has for that case. My tests are asserting @!has.

@GuillaumeGomez

This comment has been minimized.

Copy link
Member

GuillaumeGomez commented Jan 6, 2020

Indeed, my bad. Didn't see this change. Well then, looks all good to me. Thanks @dtolnay !

@bors: r+

@bors

This comment has been minimized.

Copy link
Contributor

bors commented Jan 6, 2020

📌 Commit 90adafb has been approved by GuillaumeGomez

@dtolnay

This comment has been minimized.

Copy link
Member Author

dtolnay commented Jan 6, 2020

Nominating for beta to avoid regressing #67851.

Dylan-DPC added a commit to Dylan-DPC/rust that referenced this pull request Jan 6, 2020
Distinguish between private items and hidden items in rustdoc

I believe rustdoc should not be conflating private items (visibility lower than `pub`) and hidden items (attribute `doc(hidden)`). This matters now that Cargo is passing --document-private-items by default for bin crates. In bin crates that rely on macros, intentionally hidden implementation details of the macros can overwhelm the actual useful internal API that one would want to document.

This PR restores the strip-hidden pass when documenting private items, and introduces a separate unstable --document-hidden-items option to skip the strip-hidden pass. The two options are orthogonal to one another.

Fixes rust-lang#67851. Closes rust-lang#60884.
bors added a commit that referenced this pull request Jan 6, 2020
Rollup of 5 pull requests

Successful merges:

 - #67875 (Distinguish between private items and hidden items in rustdoc)
 - #67880 (Handle multiple error fix suggestions carefuly)
 - #67887 (`Option::{expect,unwrap}` and `Result::{expect, expect_err, unwrap, unwrap_err}` have `#[track_caller]`)
 - #67908 (rustdoc: HTML escape const values)
 - #67929 (Formatting an example for method Vec.retain)

Failed merges:

r? @ghost
Centril added a commit to Centril/rust that referenced this pull request Jan 7, 2020
Distinguish between private items and hidden items in rustdoc

I believe rustdoc should not be conflating private items (visibility lower than `pub`) and hidden items (attribute `doc(hidden)`). This matters now that Cargo is passing --document-private-items by default for bin crates. In bin crates that rely on macros, intentionally hidden implementation details of the macros can overwhelm the actual useful internal API that one would want to document.

This PR restores the strip-hidden pass when documenting private items, and introduces a separate unstable --document-hidden-items option to skip the strip-hidden pass. The two options are orthogonal to one another.

Fixes rust-lang#67851. Closes rust-lang#60884.
bors added a commit that referenced this pull request Jan 8, 2020
Rollup of 4 pull requests

Successful merges:

 - #67820 (Parse the syntax described in RFC 2632)
 - #67875 (Distinguish between private items and hidden items in rustdoc)
 - #67901 (Split MIR building into its own crate)
 - #67977 (Updates for VxWorks)

Failed merges:

r? @ghost
JohnTitor added a commit to JohnTitor/rust that referenced this pull request Jan 8, 2020
Distinguish between private items and hidden items in rustdoc

I believe rustdoc should not be conflating private items (visibility lower than `pub`) and hidden items (attribute `doc(hidden)`). This matters now that Cargo is passing --document-private-items by default for bin crates. In bin crates that rely on macros, intentionally hidden implementation details of the macros can overwhelm the actual useful internal API that one would want to document.

This PR restores the strip-hidden pass when documenting private items, and introduces a separate unstable --document-hidden-items option to skip the strip-hidden pass. The two options are orthogonal to one another.

Fixes rust-lang#67851. Closes rust-lang#60884.
bors added a commit that referenced this pull request Jan 8, 2020
Rollup of 10 pull requests

Successful merges:

 - #67774 (Try statx for all linux-gnu target.)
 - #67781 (Move `is_min_const_fn` query to librustc_mir.)
 - #67798 (Remove wrong advice about spin locks from `spin_loop_hint` docs)
 - #67849 (Add a check for swapped words when we can't find an identifier)
 - #67875 (Distinguish between private items and hidden items in rustdoc)
 - #67887 (`Option::{expect,unwrap}` and `Result::{expect, expect_err, unwrap, unwrap_err}` have `#[track_caller]`)
 - #67955 (rustdoc: Remove more `#[doc(cfg(..))]` duplicates)
 - #67977 (Updates for VxWorks)
 - #67985 (Remove insignificant notes from CStr documentation)
 - #68003 (ci: fix wrong shared.sh import for publish_toolstate)

Failed merges:

 - #67820 (Parse the syntax described in RFC 2632)
 - #67979 (Move `intravisit` => `rustc_hir` + misc cleanup)

r? @ghost
bors added a commit that referenced this pull request Jan 8, 2020
Rollup of 10 pull requests

Successful merges:

 - #67774 (Try statx for all linux-gnu target.)
 - #67781 (Move `is_min_const_fn` query to librustc_mir.)
 - #67798 (Remove wrong advice about spin locks from `spin_loop_hint` docs)
 - #67849 (Add a check for swapped words when we can't find an identifier)
 - #67875 (Distinguish between private items and hidden items in rustdoc)
 - #67887 (`Option::{expect,unwrap}` and `Result::{expect, expect_err, unwrap, unwrap_err}` have `#[track_caller]`)
 - #67955 (rustdoc: Remove more `#[doc(cfg(..))]` duplicates)
 - #67977 (Updates for VxWorks)
 - #67985 (Remove insignificant notes from CStr documentation)
 - #68003 (ci: fix wrong shared.sh import for publish_toolstate)

Failed merges:

 - #67820 (Parse the syntax described in RFC 2632)
 - #67979 (Move `intravisit` => `rustc_hir` + misc cleanup)

r? @ghost
@bors bors merged commit 90adafb into rust-lang:master Jan 8, 2020
4 checks passed
4 checks passed
pr Build #20200104.44 succeeded
Details
pr (Linux mingw-check) Linux mingw-check succeeded
Details
pr (Linux x86_64-gnu-llvm-7) Linux x86_64-gnu-llvm-7 succeeded
Details
pr (Linux x86_64-gnu-tools) Linux x86_64-gnu-tools succeeded
Details
@dtolnay dtolnay deleted the dtolnay:hidden branch Jan 10, 2020
Dylan-DPC added a commit to Dylan-DPC/rust that referenced this pull request Jan 10, 2020
remove explicit strip-hidden pass from compiler doc generation

`strip-hidden` is now implied by `--document-private-items` with rust-lang#67875, so there's no need to specify it anymore.
Centril added a commit to Centril/rust that referenced this pull request Jan 10, 2020
remove explicit strip-hidden pass from compiler doc generation

`strip-hidden` is now implied by `--document-private-items` with rust-lang#67875, so there's no need to specify it anymore.
Centril added a commit to Centril/rust that referenced this pull request Jan 10, 2020
remove explicit strip-hidden pass from compiler doc generation

`strip-hidden` is now implied by `--document-private-items` with rust-lang#67875, so there's no need to specify it anymore.
JohnTitor added a commit to JohnTitor/rust that referenced this pull request Jan 10, 2020
remove explicit strip-hidden pass from compiler doc generation

`strip-hidden` is now implied by `--document-private-items` with rust-lang#67875, so there's no need to specify it anymore.
JohnTitor added a commit to JohnTitor/rust that referenced this pull request Jan 10, 2020
remove explicit strip-hidden pass from compiler doc generation

`strip-hidden` is now implied by `--document-private-items` with rust-lang#67875, so there's no need to specify it anymore.
ppannuto added a commit to tock/tock that referenced this pull request Jan 20, 2020
As discussed in rust-lang/rust#67875, there is a
difference between 'private' and 'hidden' items. Documenting private is
now the default for **bin** crates, but we also want documentation for
all of private library crates to be generated as well. Compare:

 - Before #1546: https://5e23ab06b4899600087c8c17--docs-tockosorg.netlify.com/nrf52/ficr/
 -  After #1546: https://deploy-preview-1546--docs-tockosorg.netlify.com/nrf52/ficr/

This restores our previous documentation
@ppannuto ppannuto mentioned this pull request Jan 20, 2020
2 of 2 tasks complete
@Mark-Simulacrum

This comment has been minimized.

Copy link
Member

Mark-Simulacrum commented Jan 23, 2020

@dtolnay @GuillaumeGomez -- this patch does not backport cleanly onto beta, and the conflicts look like some code was shifted around. Can one of you prepare a commit targeting origin/beta? Thanks!

(Note: beta promotion is scheduled for Monday next week).

@dtolnay

This comment has been minimized.

Copy link
Member Author

dtolnay commented Jan 23, 2020

Sure thing, I can take care of it.

@Mark-Simulacrum

This comment has been minimized.

Copy link
Member

Mark-Simulacrum commented Jan 23, 2020

Ah, actually, looks like I just needed to reformat librustdoc on beta. I forgot we had done that this cycle.

bors added a commit that referenced this pull request Jan 23, 2020
[beta] backports

This backports:
 * Do not ICE on malformed suggestion spans #68256
 * Distinguish between private items and hidden items in rustdoc #67875
 *  Revert parts of #66405. #67471

It also includes a few formatting commits to permit the backports to proceed cleanly (those are scoped to the relevant files, but still generate noise, of course). This was deemed easier than attempting to manually deal with the formatting.

r? @ghost
bors added a commit that referenced this pull request Jan 24, 2020
[beta] backports

This backports:
 * Do not ICE on malformed suggestion spans #68256
 * Distinguish between private items and hidden items in rustdoc #67875
 *  Revert parts of #66405. #67471

It also includes a few formatting commits to permit the backports to proceed cleanly (those are scoped to the relevant files, but still generate noise, of course). This was deemed easier than attempting to manually deal with the formatting.

r? @ghost
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.