next meeting

• [Rust Forge] Add rustdoc team processes (!)

16-05-2025

• rustdoc should include aliases in search that only partially matches

Open front-end polls

Open FCPs

• Deprecate option –test-args in favor of new insta-stable option –test-arg

Open RFCs

• Stabilize flags for doctest cross compilation
• Draft RFC: doc(consts)

Open pull requests

• use a button instead of a bar for search
• Implement RFC 3631: add rustdoc doc_cfg features
• Add new --book-location option to add a link to associated guide and generate it if local
• hide #[repr] if it isn't part of the public ABI
• Improve handling of rustdoc lints when used with raw doc fragments

14-04-2025

• High level design for more flexible type alias resolution
• How tolerant should we be about things that are technically invalid links?
• Consider allowing customization of how cfg gates are rendered

Open front-end polls

Open FCPs

Open RFCs

• Stabilize flags for doctest cross compilation
• Draft RFC: doc(consts)

10-03-2025

• Projectwide/Treewide stuff:
  • require compiler sign-off and reviews from other relevant teams for adding blocking ecosystem, custom codegen backend) test jobs to rust-lang/rust
  • project-scoped MCP
• Binary/internal doctests
  • Not sure which way to implement them:
    • Add a new --doctest flag on rustc?
    • Generate "inlined" doctests on expanded code?
  • Meeting discussion:
    • Need to be careful for "auto-detection rule": it should only be applied on publically documented items (so directly public or publically reexported)
• how to handle null checks in search.js
• Generating a documentation for tests
  • Should --document-tests pass a cfg(test) implicitly, like the --test option for rustc, or should it not?

Open front-end polls

Open FCPs

Open RFCs

• RFC 3631: doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features
  • approved, waiting for end of final comment period
• Draft RFC: doc(consts)

10-02-2025

• Make rustdoc run all rustc's passes
  • We talked about it from time to time, should we make it an official goal for our team?
    • Technical challenges
• edition-agnostic impl-Trait capturing
  • We decided to go for approach B: use latest compiler version to display it

Open front-end polls

Open FCPs

Open RFCs

• RFC 3631: doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features
• Draft RFC: doc(consts)

13-01-2025

• use a button instead of a bar for search
  • example searches on the new "search homepage"
• Type-based search for non-function items
  • clone-like items in -> Whatever searches
  • associated items in Whatever -> searches
• re-add –disable-minification to rustdoc for easier debugging
• Follow up previous discussion of RFC 3311: Add descriptive names to doctests
  • https://github.com/rust-lang/rust/pull/134530

Open front-end polls

Open FCPs

Open RFCs

• RFC 3631: doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features

09-12-2024

• edition-independent/agnostic precise capturing bounds (use<...>): yes/no?
  • context: https://github.com/rust-lang/rust/issues/127228#issuecomment-2201462571
  • context: https://rust-lang.zulipchat.com/#narrow/channel/213817-t-lang/topic/blog.20post.20about.20precise.20capture/near/477498874
• Type-based search for non-function items
• do we want type&name searches?
• consider more agressivly benchmarking rustdoc search to catch performance regressions (related issue)

Open front-end polls

Open FCPs

• Add --doctest-compilation-args option to add compilation flags to doctest compilation
• Tracking issue for Rust 2024: Fix doctest include paths
  

Open RFCs

• RFC 3631: doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features
• RFC 3311: Add descriptive names to doctests (merge: 5/8 (6 needed))
  • 3 blocking concerns: braced-unbraced, hard-errors, interoperability
  • NOTE(fmease): I'd like us to resolve these concerns in the meeting if possible.

11-11-2024

• (If aDotInTheVoid present): rustdoc-types publish check.
• add new crate: syntax to search a single crate
  • decide whether this or the popover approach is a better first step
    • If not the popover approach, what the syntax should be while keeping in mind that we could support multiple crates filtering in the future
• search: simplify rules for generics and type params (merged)
  • 1:1 mapping for generics, or 1:N?
• do we want type&name searches?
• consider more agressivly benchmarking rustdoc search to catch performance regressions (related issue)
• #[doc(fold)]
  • related: Consider adding CCI for the HIR expressions of public constants
• edition-independent/agnostic precise capturing bounds (use<...>): yes/no?
  • context: https://github.com/rust-lang/rust/issues/127228#issuecomment-2201462571
  • context: https://rust-lang.zulipchat.com/#narrow/channel/213817-t-lang/topic/blog.20post.20about.20precise.20capture/near/477498874

Open front-end polls

• Change impl items indent

Open FCPs

• Add --doctest-compilation-args option to add compilation flags to doctest compilation
• Tracking issue for Rust 2024: Fix doctest include paths
  

Open RFCs

• RFC 3631: doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features
• RFC 3311: Add descriptive names to doctests (merge: 5/8 (6 needed))
  • 3 blocking concerns: braced-unbraced, hard-errors, interoperability
  • NOTE(fmease): I'd like us to resolve these concerns in the meeting if possible.

Need RFC

• doc(canonical)
  • Showing "this item is a reexport of X" on inlined re-exports?
  • Approved
  • Waiting for someone to write the RFC

14-10-2024

• search: simplify rules for generics and type params
  • 1:1 mapping for generics, or 1:N?
• First line of documentation on collapsed impl blocks should be visible
  • Opened zulip thread
• Document generic parameter variance in rustdoc
  • team agreed that we want it
  • First implementation should be for the JSON format
  • UI discussion:
    • only show information on non-covariant items
    • Reduce "text noise" by having a link with little text to mention that the item is not covariant
• add new crate: syntax to search a single crate
  • decide whether this or the popover approach is a better first step
    • If not the popover approach, what the syntax should be while keeping in mind that we could support multiple crates filtering in the future

Open RFCs

• RFC for doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features

Need RFC

• doc(canonical)
  • Showing "this item is a reexport of X" on inlined re-exports?
  • Approved
  • Waiting for someone to write the RFC

Open FCPs

• (merge) Greatly speed up doctests by compiling compatible doctests in one file
• (poll) redesign toolbar and disclosure widgets
  • upgraded version of redesign [+]/[−] controls #113074

09-09-2024

• rustdoc standalone doctest attribute is confusing, taking up a potentially useful name
• Document generic parameter variance in rustdoc
  • team agreed that we want it
  • First implementation should be for the JSON format
  • UI discussion:
    • only show information on non-covariant items
    • Reduce "text noise" by having a link with little text to mention that the item is not covariant
• add new crate: syntax to search a single crate
  • decide whether this or the popover approach is a better first step

Open RFCs

• RFC for doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features
• Mergeable rustdoc cross-crate info
• RFC: Move rustdoc-types crate to T-Rustdoc ownership
  • What's missing for it to be approved?
    • aDotInTheVoid needs to add clarifications then they will start the FCP

Open FCPs

• (merge) Greatly speed up doctests by compiling compatible doctests in one file
• (poll) redesign toolbar and disclosure widgets
  • upgraded version of redesign [+]/[−] controls #113074

12-08-2024

• rustdoc-search: simplify rules for generics and type params #127589
  • Does this solve the "bug with type parameters" blocking concern on [rustdoc-search: show type signature on type-driven SERP
  • camelid: working on hiding children of blanket impls in type-based search
    #124544](https://github.com/rust-lang/rust/pull/124544)?
• document-private-items makes aliased types expansion see through private fields
  • Should we only expand local types?
• doc(canonical)
  • Showing "this item is a reexport of X" on inlined re-exports?
  • Approved
  • Waiting for someone to write the RFC
• Document generic parameter variance in rustdoc
  • team agreed that we want it
  • First implementation should be for the JSON format
  • UI discussion:
    • only show information on non-covariant items
    • Reduce "text noise" by having a link with little text to mention that the item is not covariant
• hide #[repr] if it isn't part of the public ABI
  • Fundamental question: Should we hide #[repr] all the time?
    • PRO: rustdoc doesn't need to impl sophisticated heuristics which can't be perfect anyways atm due to #114952 forcing users to write down guarantees in prose in some scenarios.
    • CON: In almost all reasonable cases, the WIP heuristic does work flawlessly and I'd argue that the presence/absence of #[repr] is a helpful quick-to-read indicator for users
    • CON: We've already implemented a sophisticated and FCP'ed heuristic for repr(transparent) (#115439). It's only logical to extend it to other #[repr]s.
  • Should we hide #[repr] if all enum variants are private/hidden or if some are? See also.
  • Should we hide it only if all struct fields are private/hidden or if some are? What about doc(hidden) on enum variant fields? Should we take them into account? See also.
  • Should we apply the same logic to all representation hints (C, uN, iN, simd, packed, aligned)?

Open RFCs

• RFC for doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features
• Mergeable rustdoc cross-crate info
• RFC: Move rustdoc-types crate to T-Rustdoc ownership
  • What's missing for it to be approved?
    • aDotInTheVoid needs to add clarifications then they will start the FCP

Open FCPs

• (merge) Greatly speed up doctests by compiling compatible doctests in one file
• (merge) redesign [+]/[−] controls
  • Need to comment why not using triangles
  • Resolve concern?
    • jsha is taking a look

08-07-2024

• "Quick feedback round": New subteam rustdoc-frontend.
• Goals of the rustdoc team?
  • Guillaume: Find more information about what is expected more exactly
  • Potential goals:
    • further simplify UI
    • use rustc_middle more, once lazy_type_alias is stabilized, so that type aliases are shown properly everywhere. and reduce inconsistency with cross-crate re-eexports
    • also generally clean up edge cases (like case sensitivity, e.g. SelfTy keyword issue)
• document-private-items makes aliased types expansion see through private fields
  • Should we only expand local types?
• RFC: Move rustdoc-types crate to T-Rustdoc ownership
  • What's missing for it to be approved?
    • aDotInTheVoid needs to add clarifications then they will start the FCP
• doc(canonical)
  • Showing "this item is a reexport of X" on inlined re-exports?
  • Approved
  • Waiting for someone to write the RFC
• Document generic parameter variance in rustdoc
  • team agreed that we want it
  • First implementation should be for the JSON format
  • UI discussion:
    • only show information on non-covariant items
    • Reduce "text noise" by having a link with little text to mention that the item is not covariant
• hide #[repr] if it isn't part of the public ABI
  • Fundamental question: Should we hide #[repr] all the time?
    • PRO: rustdoc doesn't need to impl sophisticated heuristics which can't be perfect anyways atm due to #114952 forcing users to write down guarantees in prose in some scenarios.
    • CON: In almost all reasonable cases, the WIP heuristic does work flawlessly and I'd argue that the presence/absence of #[repr] is a helpful quick-to-read indicator for users
    • CON: We've already implemented a sophisticated and FCP'ed heuristic for repr(transparent) (#115439). It's only logical to extend it to other #[repr]s.
  • Should we hide #[repr] if all enum variants are private/hidden or if some are? See also.
  • Should we hide it only if all struct fields are private/hidden or if some are? What about doc(hidden) on enum variant fields? Should we take them into account? See also.
  • Should we apply the same logic to all representation hints (C, uN, iN, simd, packed, aligned)?

Open RFCs

• RFC for doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features
• Mergeable rustdoc cross-crate info

Open FCPs

• (merge) redesign [+]/[−] controls
  • Need to comment why not using triangles
  • Resolve concern?
    • jsha is taking a look

10-06-2024

To discuss

• Goals of the rustdoc team?
  • Guillaume: Find more information about what is expected more exactly
  • Potential goals:
    • further simplify UI
    • use rustc_middle more, once lazy_type_alias is stabilized, so that type aliases are shown properly everywhere. and reduce inconsistency with cross-crate re-eexports
    • also generally clean up edge cases (like case sensitivity, e.g. SelfTy keyword issue)
• Follow model from compiler team changes and instead add roles?
  • Need to discuss exactly what we want to "take" from this RFC that applies to the rustdoc team
• document-private-items makes aliased types expansion see through private fields
  • Should we only expand local types?
• RFC: Move rustdoc-types crate to T-Rustdoc ownership
  • What's missing for it to be approved?
    • aDotInTheVoid needs to add clarifications then they will start the FCP
• doc(canonical)
  • Showing "this item is a reexport of X" on inlined re-exports?
  • Approved
  • Waiting for someone to write the RFC
• Document generic parameter variance in rustdoc
  • team agreed that we want it
  • First implementation should be for the JSON format
  • UI discussion:
    • only show information on non-covariant items
    • Reduce "text noise" by having a link with little text to mention that the item is not covariant
• hide #[repr] if it isn't part of the public ABI
  • Fundamental question: Should we hide #[repr] all the time?
    • PRO: rustdoc doesn't need to impl sophisticated heuristics which can't be perfect anyways atm due to #114952 forcing users to write down guarantees in prose in some scenarios.
    • CON: In almost all reasonable cases, the WIP heuristic does work flawlessly and I'd argue that the presence/absence of #[repr] is a helpful quick-to-read indicator for users
    • CON: We've already implemented a sophisticated and FCP'ed heuristic for repr(transparent) (#115439). It's only logical to extend it to other #[repr]s.
  • Should we hide #[repr] if all enum variants are private/hidden or if some are? See also.
  • Should we hide it only if all struct fields are private/hidden or if some are? What about doc(hidden) on enum variant fields? Should we take them into account? See also.
  • Should we apply the same logic to all representation hints (C, uN, iN, simd, packed, aligned)?

Open RFCs

• RFC for doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features

Open FCPs

• (merge) redesign [+]/[−] controls
  • Need to comment why not using triangles
  • Resolve concern?
    • jsha is taking a look

13-05-2024

To discuss

• Promote @fmease as full member of the rustdoc team?
  • Need to open the PR
• Follow model from compiler team changes and instead add roles?
  • Need to discuss exactly what we want to "take" from this RFC that applies to the rustdoc team
• document-private-items makes aliased types expansion see through private fields
  • Should we only expand local types?
• RFC: Move rustdoc-types crate to T-Rustdoc ownership
  • What's missing for it to be approved?
    • aDotInTheVoid needs to add clarifications then they will start the FCP
• doc(canonical)
  • Showing "this item is a reexport of X" on inlined re-exports?
  • Approved
  • Waiting for someone to write the RFC
• Document generic parameter variance in rustdoc
  • team agreed that we want it
  • First implementation should be for the JSON format
  • UI discussion:
    • only show information on non-covariant items
    • Reduce "text noise" by having a link with little text to mention that the item is not covariant
• hide #[repr] if it isn't part of the public ABI
  • Fundamental question: Should we hide #[repr] all the time?
    • PRO: rustdoc doesn't need to impl sophisticated heuristics which can't be perfect anyways atm due to #114952 forcing users to write down guarantees in prose in some scenarios.
    • CON: In almost all reasonable cases, the WIP heuristic does work flawlessly and I'd argue that the presence/absence of #[repr] is a helpful quick-to-read indicator for users
    • CON: We've already implemented a sophisticated and FCP'ed heuristic for repr(transparent) (#115439). It's only logical to extend it to other #[repr]s.
  • Should we hide #[repr] if all enum variants are private/hidden or if some are? See also.
  • Should we hide it only if all struct fields are private/hidden or if some are? What about doc(hidden) on enum variant fields? Should we take them into account? See also.
  • Should we apply the same logic to all representation hints (C, uN, iN, simd, packed, aligned)?

Open RFCs

• RFC for doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features

Open FCPs

• (merge) redesign [+]/[−] controls
  • Need to comment why not using triangles
  • Resolve concern?
    • jsha is taking a look
• (merge) Add support for –remap-path-prefix
  • Just waiting for everyone to approve

08-04-2024

To discuss

• Always display stability version even if it's the same as the containing item
  • team seems to be shared about this
• doc(canonical)
  • Showing "this item is a reexport of X" on inlined re-exports?
  • Approved.
• rustdoc-search: single result for items with multiple paths
• Document generic parameter variance in rustdoc
  • team agreed that we want it
  • First implementation should be for the JSON format
  • UI discussion:
    • only show information on non-covariant items
    • Reduce "text noise" by having a link with little text to mention that the item is not covariant
• hide #[repr] if it isn't part of the public ABI
  • Fundamental question: Should we hide #[repr] all the time?
    • PRO: rustdoc doesn't need to impl sophisticated heuristics which can't be perfect anyways atm due to #114952 forcing users to write down guarantees in prose in some scenarios.
    • CON: In almost all reasonable cases, the WIP heuristic does work flawlessly and I'd argue that the presence/absence of #[repr] is a helpful quick-to-read indicator for users
    • CON: We've already implemented a sophisticated and FCP'ed heuristic for repr(transparent) (#115439). It's only logical to extend it to other #[repr]s.
  • Should we hide #[repr] if all enum variants are private/hidden or if some are? See also.
  • Should we hide it only if all struct fields are private/hidden or if some are? What about doc(hidden) on enum variant fields? Should we take them into account? See also.
  • Should we apply the same logic to all representation hints (C, uN, iN, simd, packed, aligned)?

Open FCPs

• (merge) redesign [+]/[−] controls
  • Need to comment why not using triangles
  • Resolve concern?
    • jsha is taking a look
• (close) Add support for –remap-path-prefix
• (merge) Add / key to focus on search input

11-03-2024

To discuss

• search types by higher-order functions: should we continue to increase the syntax complexity for the search to have more advanced search features?
  • the team accepted this feature
    Image Not Showing Possible Reasons

    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported

    Learn More →
• Add unstable --test-builder-wrapper flag
  • Accepted by the team
• doc(canonical)
  • Team is in favor of this feature, just not sure how to address it.
• Showing "this item is a reexport of X" on inlined re-exports?
• Document generic parameter variance in rustdoc
  • team agreed that we want it
  • First implementation should be for the JSON format
  • UI discussion:
    • only show information on non-covariant items
    • Reduce "text noise" by having a link with little text to mention that the item is not covariant
• hide #[repr] if it isn't part of the public ABI
  • Fundamental question: Should we hide #[repr] all the time?
    • PRO: rustdoc doesn't need to impl sophisticated heuristics which can't be perfect anyways atm due to #114952 forcing users to write down guarantees in prose in some scenarios.
    • CON: In almost all reasonable cases, the WIP heuristic does work flawlessly and I'd argue that the presence/absence of #[repr] is a helpful quick-to-read indicator for users
    • CON: We've already implemented a sophisticated and FCP'ed heuristic for repr(transparent) (#115439). It's only logical to extend it to other #[repr]s.
  • Should we hide #[repr] if all enum variants are private/hidden or if some are? See also.
  • Should we hide it only if all struct fields are private/hidden or if some are? What about doc(hidden) on enum variant fields? Should we take them into account? See also.
  • Should we apply the same logic to all representation hints (C, uN, iN, simd, packed, aligned)?

Open FCPs

• (merge) redesign [+]/[−] controls
  • Need to comment why not using triangles
  • Resolve concern?
    • jsha is taking a look
• (close) Always display stability version even if it's the same as the containing item
  • Guillaume, Alona and Nemo seem in favor to show the stability version all the time. Not enough time to be discussed. Postponed to next meeting.

12-02-2024

To discuss

• Checkbox to hide unstable things?
  • rejected
• Document generic parameter variance in rustdoc
  • team agreed that we want it
  • First implementation should be for the JSON format
  • UI discussion:
    • only show information on non-covariant items
    • Reduce "text noise" by having a link with little text to mention that the item is not covariant
• hide #[repr] if it isn't part of the public ABI
  • Fundamental question: Should we hide #[repr] all the time?
    • PRO: rustdoc doesn't need to impl sophisticated heuristics which can't be perfect anyways atm due to #114952 forcing users to write down guarantees in prose in some scenarios.
    • CON: In almost all reasonable cases, the WIP heuristic does work flawlessly and I'd argue that the presence/absence of #[repr] is a helpful quick-to-read indicator for users
    • CON: We've already implemented a sophisticated and FCP'ed heuristic for repr(transparent) (#115439). It's only logical to extend it to other #[repr]s.
  • Should we hide #[repr] if all enum variants are private/hidden or if some are? See also.
  • Should we hide it only if all struct fields are private/hidden or if some are? What about doc(hidden) on enum variant fields? Should we take them into account? See also.
  • Should we apply the same logic to all representation hints (C, uN, iN, simd, packed, aligned)?
• Prefer full reference links for intra-doc links
• Add unstable --test-builder-wrapper flag
• doc(canonical)
• Showing "this item is a reexport of X" on inlined re-exports?
• search types by higher-order functions: should we continue to increase the syntax complexity for the search to have more advanced search features?

Open FCPs

• (merge) redesign [+]/[−] controls
  • Need to comment why not using triangles
  • Resolve concern?
    • jsha is taking a look
• (close) Always display stability version even if it's the same as the containing item
  • More general policy question: what's the burden of evidence for making a change like this? It seems like most of the evidence we could gather is already here.

08-01-2024

To discuss

• RFC 3505: Move rustdoc-types crate to T-Rustdoc ownership
  • Discussions still in progress on the RFC
• Some items don't have documentation rendered
  • Need to write a document explaining in detail what this is about
    • https://hackmd.io/utkhPlwpSyCvB-LE8KmyIw
    • Rejected.
• Checkbox to hide unstable things?
  • not discussed
• Adding #[doc(allow_unknown)] attribute? Linked to Turn INVALID_DOC_ATTRIBUTES lint into a hard error starting edition 2024
  • Otherwise that would mean that using new doc attributes could force to change MSRV.
  • Most people seem in favour to turn it into a hard error starting 2024 edition
  • Decided to keep it as lint by denied by default.
• Document generic parameter variance in rustdoc
  • Discussion started, but no clear decision for now.
• hide #[repr] if it isn't part of the public ABI
  • Fundamental question: Should we hide #[repr] all the time?
    • PRO: rustdoc doesn't need to impl sophisticated heuristics which can't be perfect anyways atm due to #114952 forcing users to write down guarantees in prose in some scenarios.
    • CON: In almost all reasonable cases, the WIP heuristic does work flawlessly and I'd argue that the presence/absence of #[repr] is a helpful quick-to-read indicator for users
    • CON: We've already implemented a sophisticated and FCP'ed heuristic for repr(transparent) (#115439). It's only logical to extend it to other #[repr]s.
  • Should we hide #[repr] if all enum variants are private/hidden or if some are? See also.
  • Should we hide it only if all struct fields are private/hidden or if some are? What about doc(hidden) on enum variant fields? Should we take them into account? See also.
  • Should we apply the same logic to all representation hints (C, uN, iN, simd, packed, aligned)?
• Prefer full reference links for intra-doc links
• Add unstable --test-builder-wrapper flag

Open FCPs

• (merge) redesign [+]/[−] controls
  • Need to comment why not using triangles
  • Resolve concern?
• (merge) Should rustdoc support links in headings?
  • Some changes to be done to unify headings
• (close) Add a default flag for enum documentation
  • A lot of concerns were raised about the limits of the current feature implementation and the limits of the potential "extension" (ie checking Default trait impl directly).
• (close) Always display stability version even if it's the same as the containing item
  • More general policy question: what's the burden of evidence for making a change like this? It seems like most of the evidence we could gather is already here.

04-12-2023

To discuss

• Some items don't have documentation rendered
  • Need to write a document explaining in detail what this is about
    • Not done yet.
• Adding #[doc(allow_unknown)] attribute? Linked to Turn INVALID_DOC_ATTRIBUTES lint into a hard error starting edition 2024
  • Otherwise that would mean that using new doc attributes could force to change MSRV.
  • Most people seem in favour to turn it into a hard error starting 2024 edition
• Document generic parameter variance in rustdoc
• hide #[repr] if it isn't part of the public ABI
  • Fundamental question: Should we hide #[repr] all the time?
    • PRO: rustdoc doesn't need to impl sophisticated heuristics which can't be perfect anyways atm due to #114952 forcing users to write down guarantees in prose in some scenarios.
    • CON: In almost all reasonable cases, the WIP heuristic does work flawlessly and I'd argue that the presence/absence of #[repr] is a helpful quick-to-read indicator for users
    • CON: We've already implemented a sophisticated and FCP'ed heuristic for repr(transparent) (#115439). It's only logical to extend it to other #[repr]s.
  • Should we hide #[repr] if all enum variants are private/hidden or if some are? See also.
  • Should we hide it only if all struct fields are private/hidden or if some are? What about doc(hidden) on enum variant fields? Should we take them into account? See also.
  • Should we apply the same logic to all representation hints (C, uN, iN, simd, packed, aligned)?
• Prefer full reference links for intra-doc links

Open FCPs

• redesign [+]/[−] controls
  • Need to comment why not using triangles
  • Resolve concern?
• Don't merge cfg and doc(cfg) attributes for re-exports
  • Approved.
• Should rustdoc support links in headings?
  • Some changes to be done to unify headings
• allow resizing the sidebar / hiding the top bar
  • Approved.
• Add a default flag for enum documentation
  • A lot of concerns were raised about the limits of the current feature implementation and the limits of the potential "extension" (ie checking Default trait impl directly).
• search for tuples and unit by type with ()
• Always display stability version even if it's the same as the containing item
  • More general policy question: what's the burden of evidence for making a change like this? It seems like most of the evidence we could gather is already here.

06-11-2023

To discuss

• Should rustdoc support links in headings?
  • Need an implementation and a live website so people can test it out.
• Some items don't have documentation rendered
  • Need to write a document explaning in detail what this is about
• Adding #[doc(allow_unknown)] attribute? Linked to Turn INVALID_DOC_ATTRIBUTES lint into a hard error starting edition 2024
  • Otherwise that would mean that using new doc attributes could force to change MSRV.
  • Most people seem in favour to turn it into a hard error starting 2024 edition
• Document generic parameter variance in rustdoc
• hide #[repr] if it isn't part of the public ABI
  • Fundamental question: Should we hide #[repr] all the time?
    • PRO: rustdoc doesn't need to impl sophisticated heuristics which can't be perfect anyways atm due to #114952 forcing users to write down guarantees in prose in some scenarios.
    • CON: In almost all reasonable cases, the WIP heuristic does work flawlessly and I'd argue that the presence/absence of #[repr] is a helpful quick-to-read indicator for users
    • CON: We've already implemented a sophisticated and FCP'ed heuristic for repr(transparent) (#115439). It's only logical to extend it to other #[repr]s.
  • Should we hide #[repr] if all enum variants are private/hidden or if some are? See also.
  • Should we hide it only if all struct fields are private/hidden or if some are? What about doc(hidden) on enum variant fields? Should we take them into account? See also.
  • Should we apply the same logic to all representation hints (C, uN, iN, simd, packed, aligned)?
• Prefer full reference links for intra-doc links

Open FCPs

• Add a default flag for enum documentation
• Don't merge cfg and doc(cfg) attributes for re-exports
• allow resizing the sidebar / hiding the top bar
• redesign [+]/[−] controls
• rustdoc-search: add support for traits and associated types

Finished FCPs

• hide #[repr(transparent)] if it isn't part of the public ABI
• Document lack of object safety on affected traits
  

Any bugs than should be prioritized to be fixed?

02-10-2023

To discuss

• call for rustdoc-types maintainers
  • Is it worth posting this as a pre-rfc to IRLO, or should I just go straigh to RFC PR?
  • Planning to make an RFC. Draft is here: https://hackmd.io/@aDot/SJ3KnH8A3
• Add a default flag for enum documentation
  • Team agrees to add the feature but more discussions are required about the possibility to disable it
• Documentation size can grow significantly due to documentation of impls on type aliases
  • Team agrees that the size increase is problematic. Potential solution would be to handle it with JS like we do with foreign traits impls.
• Show enum variant value if it is a C-like variant
  • Team agrees with the feature. Some parts are missing, PR needs to be updated.

Open FCPs

• rustdoc: hide #[repr(transparent)] if it isn't part of the public ABI
• rustdoc search: add impl disambiguator to duplicate assoc items

Issues needing discussion

• Should rustdoc support links in headings?
• Some items don't have documentation rendered

Any bugs than should be prioritized to be fixed?

04-09-2023

To discuss

• Add fmease to rustdoc review rotations
  • GuillaumeGomez: Approved.

Open FCPs

• rustdoc search: add impl disambiguator to duplicate assoc items
  • notriddle: Since the last meeting, an additional section has been added that describes the bug being fixed in more detail.
• Don't merge cfg and doc(cfg) attributes for re-exports
  • notriddle: This seems to be blocked on glob imports?
• rustdoc-search: add support for type parameters
  • notriddle: Since the last meeting, sample queries have been added to the "Motivation" section.
  • GuillaumeGomez: Approved.
• show inner enum and struct in type definition for concrete type
  • notriddle: This PR is in FCP right now.
  • GuillaumeGomez: Approved.

Items needing discussion

• RFC: Cargo feature descriptions & metadata
  
  • rustdoc part: https://github.com/rust-lang/rfcs/pull/3421/files
  • notriddle: Not sure if blocked on Rustdoc, or on Cargo.
• align stability badge to baseline instead of bottom
  • notriddle: It seems like there's an unmoving situation where everyone just disagrees on what "looks right."
• Strikethrough deprecated items in sidebar
  • notriddle: No movement for months. Everyone (read: GuillaumeGomez) who has commented on this says that strikethrough is a bad way to do it. To progress, an alternative is needed?
  • GuillaumeGomez: Rejected.

Issues needing discussion

• Is rustdoc supposed to work with broken Rust code?
  • GuillaumeGomez: No consensus reached. Need to get some incencitives first with a crater run to see how many crates would be impacted by this change first. It would still very likely require to be done as part as a new edition.
• Some items don't have documentation rendered
• Should rustdoc support links in headings?

Any bugs than should be prioritized to be fixed?

07-08-2023

Open FCPs

• Accept additional user-defined classes in fenced code blocks
  • Accepted
• Add warning block support in rustdoc
  • Did everyone answer the poll? (https://score.vote/gpBi43e7kr/results)
    • We might want to pick another way to get answers for similar cases in the future since it's complicated to answer it.
  • Status: Accepted, need imperio and notriddle to pick one UI and move forward with it.
• rustdoc search: add impl disambiguator to duplicate assoc items
  • notriddle will add screenshots to depict the problem.
• Don't merge cfg and doc(cfg) attributes for re-exports

Items needing discussion

• RFC: Cargo feature descriptions & metadata
  
  • rustdoc part: https://github.com/rust-lang/rfcs/pull/3421/files
• align stability badge to baseline instead of bottom

Issues needing discussion

• Is rustdoc supposed to work with broken Rust code?
• Some items don't have documentation rendered
• Should rustdoc support links in headings?
• askama migration: the code is more complex than before and tend to have worse performance. So is it really worth it?

Any bugs than should be prioritized to be fixed?

03-07-2023

Open FCPs

• Accept additional user-defined classes in fenced code blocks
  • Missing explanations in the PR: improve the description
  • Add missing use cases from the original PR
  • Add use cases and rationale on the tracking issue as well
• Allow whitespace as path separator like double colon
  • Merged.
• Add warning block support in rustdoc
  • Team agreed on the markdown syntax for this feature: plain HTML
  • Need to make a poll so rustdoc team members can pick their preferred UI.
• rustdoc search: add impl disambiguator to duplicate assoc items
  • No disagreement.
• rustdoc-search: add support for type parameters
• Don't merge cfg and doc(cfg) attributes for re-exports

Items needing discussion

• RFC: Cargo feature descriptions & metadata
  

Issues needing discussion

• Some items don't have documentation rendered
• Should rustdoc support links in headings?
• askama migration: the code is more complex than before and tend to have worse performance. So is it really worth it?

Any bugs than should be prioritized to be fixed?