rustdoc book: acknowledge --document-hidden-items #132876

lolbinarycat · 2024-11-10T21:05:40Z

No description provided.

rustbot · 2024-11-10T21:05:48Z

rustbot has assigned @GuillaumeGomez.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

aDotInTheVoid · 2024-11-10T21:12:43Z

src/doc/rustdoc/src/command-line-arguments.md

-`--document-private-items` documents all items, even if they're not public.
+`--document-private-items` causes all items to be documented as if they were `pub`.
+
+## `--document-hidden-items`: Show items that are `#[doc(hidden)]`


This should be on the page for unstable features, as it currently requires -Z unstable-options

oh, that's weird, rustdoc --help shows it with the stable options.

oh.. yeah there's very little logic to how that's sorted...

Command line option parsing was changed recently in #132754. Maybe it did something wrong? If not, we need to fix that.

I think "rustdoc doesn't make it clear what options are unstable" is a longstanding issue, attempts at fixing it have been made before, but I believe they were reverted.

aDotInTheVoid · 2024-11-10T21:13:06Z

src/doc/rustdoc/src/command-line-arguments.md

+
+`--document-hidden-items` causes all items to be documented as if they did not have `#[doc(hidden)]`.
+
+items that are hidden and private will only be documented if both `--document-hidden-items` *and* `--document-private-items` are specified.


Suggested change

items that are hidden and private will only be documented if both `--document-hidden-items` *and* `--document-private-items` are specified.

Items that are hidden and private will only be documented if both `--document-hidden-items` *and* `--document-private-items` are specified.

src/doc/rustdoc/src/write-documentation/the-doc-attribute.md

aDotInTheVoid · 2024-11-10T21:19:02Z

r? @aDotInTheVoid

GuillaumeGomez · 2024-11-10T21:21:08Z

src/doc/rustdoc/src/command-line-arguments.md

@@ -100,7 +100,16 @@ mod private { // this item is private and will not be documented
 }
 ```

-`--document-private-items` documents all items, even if they're not public.
+`--document-private-items` causes all items to be documented as if they were `pub`.


It's actually not the case. It shows them up with a little lock alongside them, but it's not the same as if they were pub.

I mean that the logic for whether or not they are included will be the same as that for pub items.

The previous wording implied that it also shows doc(hidden) items, which it does not.

I am not sure how to word it more clearly without being overly verbose.

What do you think about:

--document-private-items includes all non-public in the generated documentation, but not #[doc(hidden)] items.

?

I would say "except for", but other than that, it should be fine as long as we don't add another separate condition that prevents items from being documented.

Sounds good. :)

GuillaumeGomez · 2024-11-10T21:22:16Z

src/doc/rustdoc/src/command-line-arguments.md

+
+## `--document-hidden-items`: Show items that are `#[doc(hidden)]`
+
+By default, `rustdoc` does not document items that are annotated with


That's a bit weird to specify it, it's literally the original meaning. I suppose you wanted to underline that #[doc(hidden)] items were documented with this option? If so please reword it.

I was mirroring the wording of --document-private-items

GuillaumeGomez · 2024-11-10T21:22:43Z

src/doc/rustdoc/src/command-line-arguments.md

+By default, `rustdoc` does not document items that are annotated with
+[`#[doc(hidden)]`](write-documentation/the-doc-attribute.html#hidden).
+
+`--document-hidden-items` causes all items to be documented as if they did not have `#[doc(hidden)]`.


I think you can remove this paragraph, it's what is said in the first line of this diff already so no need for repetition.

You mean the heading? I'm following the existing style of other sections, which is that the body of a section should make sense without its heading.

GuillaumeGomez · 2024-11-10T21:23:18Z

src/doc/rustdoc/src/command-line-arguments.md

+
+`--document-hidden-items` causes all items to be documented as if they did not have `#[doc(hidden)]`.
+
+items that are hidden and private will only be documented if both `--document-hidden-items` *and* `--document-private-items` are specified.


I think it'd be better to say that private items will not be displayed with this option and that to have both, you need both options.

that private items will not be displayed with this option

That's not strictly true, the option merely has no effect on if private items will be documented.

GuillaumeGomez · 2024-11-10T21:24:15Z

src/doc/rustdoc/src/write-documentation/the-doc-attribute.md

-`#[doc(hidden)]` will be considered the same as private.
+Any item annotated with `#[doc(hidden)]` will not appear in the documentation,
+unless the `--document-hidden-items` flag is used.
+Re-exported items where one of its ancestors has


Hum... This part needs clarification about what "ancestor" is because re-exports of hidden items are displayed.

Yeah it sure does! I don't really have access to that information though, I'm working off of very limited documentation.

Then please remove this sentence completely.

Still waiting for this one.

Now that I've done more work on rustdoc, I'd rather just read through the source to figure this out... or maybe i'll just remove it an open an issue to investigate this.

Nope, can't replicate it, removing.

lolbinarycat · 2024-11-10T23:05:58Z

@GuillaumeGomez I'll be honest, I have no idea what you want me to do. Feedback such as "reword it" is not specific enough to be actionable. Additionally, splitting feedback into lots of little chucks like this it hard to follow, partially due to issues with the github UI.

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

GuillaumeGomez · 2024-11-11T10:30:19Z

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

+
+`--document-hidden-items` causes all items to be documented as if they did not have `#[doc(hidden)]`.
+
+Items that are hidden and private will only be documented if both `--document-hidden-items` *and* `--document-private-items` are specified.


I think this paragraph can be removed with my suggestion for the previous paragraph.

the --document-hidden-items section is already much shorter than the sections for other unstable options, why does it need to be shorter?

also, your suggestion for the previous paragraph would only contribute to the misunderstanding this paragraph is trying to prevent.

…youxu triagebot: Autolabel rustdoc book Inspired by rust-lang#132876 not getting labeled as https://github.com/rust-lang/rust/labels/T-rustdoc r? `@GuillaumeGomez`

Rollup merge of rust-lang#132881 - aDotInTheVoid:docs-for-docs, r=jieyouxu triagebot: Autolabel rustdoc book Inspired by rust-lang#132876 not getting labeled as https://github.com/rust-lang/rust/labels/T-rustdoc r? `@GuillaumeGomez`

GuillaumeGomez · 2025-02-10T20:49:58Z

Ping @lolbinarycat. I see a few comments that were not implemented yet. :)

lolbinarycat · 2025-02-10T23:51:26Z

I'll try to get back to this eventually, I've been focusing on other things and currently I can't work on anything because I don't have Internet.

lolbinarycat · 2025-02-13T19:13:21Z

@GuillaumeGomez I've added the truth table and reworded the docs for --document-private-items, most of the other stuff I feel like should stay for completeness or consistency. Is there anything you think absolutely needs to be changed?

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

src/doc/rustdoc/src/command-line-arguments.md

lolbinarycat · 2025-02-14T18:25:24Z

@GuillaumeGomez visibility marker icons are now documented

GuillaumeGomez · 2025-02-20T20:55:54Z

Looks good to me, thanks! Please squash your commits then r=me

lolbinarycat · 2025-02-20T23:07:40Z

r=@GuillaumeGomez

GuillaumeGomez · 2025-02-20T23:08:31Z

@bors delegate=lolbinarycat

bors · 2025-02-20T23:08:35Z

✌️ @lolbinarycat, you can now approve this pull request!

If @GuillaumeGomez told you to "r=me" after making some further change, please make that change, then do @bors r=@GuillaumeGomez

GuillaumeGomez · 2025-02-20T23:08:49Z

And please wait for CI to be done before r+ing.

lolbinarycat · 2025-02-20T23:30:29Z

@GuillaumeGomez shouldn't this get rolled up, as a documentation change?

GuillaumeGomez · 2025-02-20T23:31:21Z

Yes it should, add "rollup" after the "r=me" command.

lolbinarycat · 2025-02-21T00:59:36Z

@bors r=@GuillaumeGomez rollup

bors · 2025-02-21T00:59:38Z

📌 Commit ff7533e has been approved by GuillaumeGomez

It is now in the queue for this repository.

…iaskrgr Rollup of 10 pull requests Successful merges: - rust-lang#132876 (rustdoc book: acknowledge --document-hidden-items) - rust-lang#136148 (Optionally add type names to `TypeId`s.) - rust-lang#136609 (libcore/net: `IpAddr::as_octets()`) - rust-lang#137336 (Stabilise `os_str_display`) - rust-lang#137350 (Move methods from Map to TyCtxt, part 3.) - rust-lang#137353 (Implement `read_buf` for WASI stdin) - rust-lang#137361 (Refactor `OperandRef::extract_field` to prep for MCP838) - rust-lang#137367 (Do not exempt nonexistent platforms from platform policy) - rust-lang#137374 (Stacker now handles miri using a noop impl itself) - rust-lang#137392 (remove few unused fields) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of rust-lang#132876 - lolbinarycat:rustdoc-document-hidden-items, r=GuillaumeGomez rustdoc book: acknowledge --document-hidden-items

…iaskrgr Rollup of 10 pull requests Successful merges: - rust-lang#132876 (rustdoc book: acknowledge --document-hidden-items) - rust-lang#136148 (Optionally add type names to `TypeId`s.) - rust-lang#136609 (libcore/net: `IpAddr::as_octets()`) - rust-lang#137336 (Stabilise `os_str_display`) - rust-lang#137350 (Move methods from Map to TyCtxt, part 3.) - rust-lang#137353 (Implement `read_buf` for WASI stdin) - rust-lang#137361 (Refactor `OperandRef::extract_field` to prep for MCP838) - rust-lang#137367 (Do not exempt nonexistent platforms from platform policy) - rust-lang#137374 (Stacker now handles miri using a noop impl itself) - rust-lang#137392 (remove few unused fields) r? `@ghost` `@rustbot` modify labels: rollup

rustbot assigned GuillaumeGomez Nov 10, 2024

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Nov 10, 2024

aDotInTheVoid reviewed Nov 10, 2024

View reviewed changes

rustbot assigned aDotInTheVoid and unassigned GuillaumeGomez Nov 10, 2024

GuillaumeGomez reviewed Nov 10, 2024

View reviewed changes

aDotInTheVoid added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Nov 10, 2024

aDotInTheVoid mentioned this pull request Nov 10, 2024

triagebot: Autolabel rustdoc book #132881

Merged

This comment has been minimized.

Sign in to view

GuillaumeGomez reviewed Nov 11, 2024

View reviewed changes

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

GuillaumeGomez reviewed Nov 11, 2024

View reviewed changes

aDotInTheVoid changed the title ~~rustdoc book: acknowlage --document-hidden-items~~ rustdoc book: acknowledge --document-hidden-items Dec 9, 2024

GuillaumeGomez reviewed Feb 14, 2025

View reviewed changes

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

GuillaumeGomez reviewed Feb 14, 2025

View reviewed changes

src/doc/rustdoc/src/command-line-arguments.md Outdated Show resolved Hide resolved

GuillaumeGomez approved these changes Feb 20, 2025

View reviewed changes

rustdoc book: acknowlage --document-hidden-items

ff7533e

lolbinarycat force-pushed the rustdoc-document-hidden-items branch from aa0ac7a to ff7533e Compare February 20, 2025 23:06

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 Feb 21, 2025

matthiaskrgr mentioned this pull request Feb 21, 2025

Rollup of 10 pull requests #137397

Merged

bors merged commit 4395618 into rust-lang:master Feb 21, 2025
6 checks passed

rustbot added this to the 1.87.0 milestone Feb 21, 2025

rust-timer added a commit to rust-lang-ci/rust that referenced this pull request Feb 21, 2025

Unrolled build for rust-lang#132876

0572d2b

Rollup merge of rust-lang#132876 - lolbinarycat:rustdoc-document-hidden-items, r=GuillaumeGomez rustdoc book: acknowledge --document-hidden-items


		`--document-hidden-items` causes all items to be documented as if they did not have `#[doc(hidden)]`.

		items that are hidden and private will only be documented if both `--document-hidden-items` and `--document-private-items` are specified.


		## `--document-hidden-items`: Show items that are `#[doc(hidden)]`

		By default, `rustdoc` does not document items that are annotated with

rustdoc book: acknowledge --document-hidden-items #132876

rustdoc book: acknowledge --document-hidden-items #132876

Conversation

lolbinarycat commented Nov 10, 2024

rustbot commented Nov 10, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aDotInTheVoid commented Nov 10, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lolbinarycat commented Nov 10, 2024

This comment has been minimized.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GuillaumeGomez commented Feb 10, 2025

lolbinarycat commented Feb 10, 2025

lolbinarycat commented Feb 13, 2025

lolbinarycat commented Feb 14, 2025

GuillaumeGomez commented Feb 20, 2025

lolbinarycat commented Feb 20, 2025

GuillaumeGomez commented Feb 20, 2025

bors commented Feb 20, 2025

GuillaumeGomez commented Feb 20, 2025

lolbinarycat commented Feb 20, 2025

GuillaumeGomez commented Feb 20, 2025

lolbinarycat commented Feb 21, 2025

bors commented Feb 21, 2025