rustdoc: Appearance of #[doc(hidden)] differs from all the other attributes
#132304
Assignees
Labels
A-attributes
Area: Attributes (`#[…]`, `#![…]`)
A-rustdoc-ui
Area: Rustdoc UI (generated HTML)
C-bug
Category: This is a bug.
P-low
Low priority
requires-nightly
This issue requires a nightly compiler in some way.
T-rustdoc
Relevant to the rustdoc team, which will review and decide on the PR/issue.
Comments
fmease
added
A-attributes
rustbot
added
the
needs-triage
fmease
removed
the
needs-triage
fmease
changed the title
#[doc(hidden)] differs from all other attributes#[doc(hidden)] differs from all the other attributes
|
Screenshot is broken :( |
|
Oops, fixed. The link pointed into my private issue tracker. Reuploaded. Thanks for the notice :) |
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this issue
Nov 13, 2024
…o-decl, r=notriddle rustdoc: Treat declarative macros more like other item kinds Apparently at some time in the past we were unable to generate an href for the module path inside the visibility of decl macros 2.0 (`pub(in ...)`). As a result of this, a whole separate function was introduced specifically for printing the visibility of decl macros that didn't attempt to generate any links. The description of PR rust-lang#84074 states: > This fixes the overly-complex invariant mentioned in rust-lang#83237 (comment), where the macro source can't have any links in it only because the cache hasn't been populated yet. I can no longer reproduce the original issue. Reusing the existing visibility rendering logic *seems* to work just fine (I couldn't come up with any counterexamples, though I invite you to prove me wrong). * Fixes rust-lang#83000 * Fixes the visibility showing up "twice" in rustdoc-JSON output: Once as the `visibility` field, once baked into the source[^1] * Fixes `#[doc(hidden)]` not getting rendered on doc(hidden) decl macros 2.0 under `--document-hiden-items` (for decl macros 1.2 the issue remains; I will address this separately when fixing rust-lang#132304). --- <details><summary>Outdated Section</summary> NOTE: The current version of this PR is committing a UI crime, I'd like to receive feedback on that. Maybe you have a satisfactory solution for how to remedy it. Namely, as you know we have two different ways of / modes for highlighting code with color: 1. Only highlighting links / item paths and avoiding to highlight tokens by kind like keywords (to reduce visual noise and maybe also artifact size). Used for item declarations(\*). 2. Highlighting tokens by kind. Used for code blocks written by the user. (\*): With the notable exception being macro declarations! Well, since this PR reuses the same function for rendering the item visibility (which only makes sense), we have a clash of modes: We now use both ways of highlighting code for decl macros: №1 for the visibility, №2 for the rest. This awkward. See for yourself: * On master:  * On this branch:  </details> Furthermore, we now no longer syntax-highlight declarative macros (be it `macro_rules!` or `macro`) since that was inconsistent with the way we render all other item kinds. See (collapsed) *Outdated Section* above. See also rust-lang#132302 (comment). | On master | On this branch | |---|---| |  |  | [^1]: E.g., `"visibility":{"restricted":{"parent":1,"path":"::a"}},/*OMITTED*/,"inner":{"macro":"pub(in a) macro by_example_vis_named($foo:expr) {\n ...\n}"}`
rust-timer
added a commit
to rust-lang-ci/rust
that referenced
this issue
Nov 14, 2024
Rollup merge of rust-lang#132302 - fmease:rustdoc-better-vis-for-macro-decl, r=notriddle rustdoc: Treat declarative macros more like other item kinds Apparently at some time in the past we were unable to generate an href for the module path inside the visibility of decl macros 2.0 (`pub(in ...)`). As a result of this, a whole separate function was introduced specifically for printing the visibility of decl macros that didn't attempt to generate any links. The description of PR rust-lang#84074 states: > This fixes the overly-complex invariant mentioned in rust-lang#83237 (comment), where the macro source can't have any links in it only because the cache hasn't been populated yet. I can no longer reproduce the original issue. Reusing the existing visibility rendering logic *seems* to work just fine (I couldn't come up with any counterexamples, though I invite you to prove me wrong). * Fixes rust-lang#83000 * Fixes the visibility showing up "twice" in rustdoc-JSON output: Once as the `visibility` field, once baked into the source[^1] * Fixes `#[doc(hidden)]` not getting rendered on doc(hidden) decl macros 2.0 under `--document-hiden-items` (for decl macros 1.2 the issue remains; I will address this separately when fixing rust-lang#132304). --- <details><summary>Outdated Section</summary> NOTE: The current version of this PR is committing a UI crime, I'd like to receive feedback on that. Maybe you have a satisfactory solution for how to remedy it. Namely, as you know we have two different ways of / modes for highlighting code with color: 1. Only highlighting links / item paths and avoiding to highlight tokens by kind like keywords (to reduce visual noise and maybe also artifact size). Used for item declarations(\*). 2. Highlighting tokens by kind. Used for code blocks written by the user. (\*): With the notable exception being macro declarations! Well, since this PR reuses the same function for rendering the item visibility (which only makes sense), we have a clash of modes: We now use both ways of highlighting code for decl macros: №1 for the visibility, №2 for the rest. This awkward. See for yourself: * On master:  * On this branch:  </details> Furthermore, we now no longer syntax-highlight declarative macros (be it `macro_rules!` or `macro`) since that was inconsistent with the way we render all other item kinds. See (collapsed) *Outdated Section* above. See also rust-lang#132302 (comment). | On master | On this branch | |---|---| |  |  | [^1]: E.g., `"visibility":{"restricted":{"parent":1,"path":"::a"}},/*OMITTED*/,"inner":{"macro":"pub(in a) macro by_example_vis_named($foo:expr) {\n ...\n}"}`
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
One reproducer where it's quite pronounced:
Output (with
--document-hidden-items -Zunstable-options1):That's because it gets rendered separately in
visibility_print_with_space. I would rather we didn't do that. It should be printed together with all the other attributes and have the same visual appearance.Footnotes
Hence the requires-nightlyThis issue requires a nightly compiler in some way.
label ↩
The text was updated successfully, but these errors were encountered: