Skip to content

#[doc(consts)] #3770

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.

Sign up for GitHub

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

Draft
wants to merge 3 commits into
base: master
Choose a base branch
from
Draft

#[doc(consts)] #3770

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
81ca826
begin work on #[doc(consts)] rfc
lolbinarycat Jan 25, 2025
701de89
provide rationale, expand edge cases and unresolved questions
lolbinarycat Feb 10, 2025
735fc4b
add normalize:: prefix
lolbinarycat May 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 146 additions & 0 deletions text/0000-doc-consts.md
View file
Open in desktop
Copy link
Member

@fmease fmease Jun 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think one good way to make proper progress on this RFC and bring it out of its draft status, would be to schedule some sort of "deep dive session" where interested parties can come together and investigate whether we as rustdoc can guarantee to take this attribute into account in all cases from an implementation perspective or whether we need to downgrade it to a "hint".

Re. "cases", I'm referring to local vs. inlined cross-crate or more precisely lowering from HIR vs middle::ty IR / MIR (ValTree, mir::Const, ty::Const).

Copy link
Member

@fmease fmease Jun 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As part of this, I'm also interested in talking about what "fold" and "expr" entail precisely, namely what guarantees we're willing to make if any.

  1. For "expr", for example whether we want to promise preserving "lexical information" like number bases (e.g., 0xFF), underscores (e.g., 1_000) (some users really love to keep this behavior (in the local case)).
    • I don't remember if it's preserved in the HIR but even if it's not, then in some cases it's obtainable via SourceMap. IIRC rustdoc currently does look at the SourceMap to achieve this
    • Obviously for the cross-crate case, middle::ty IR / MIR doesn't contain these pieces of information (and it will never do), so we'd need to use "JS side files" or something like that etc etc
  2. For "fold",
    • for example what to do if the const expr "is too generic" or if it diverges1 (hard error vs. keeping the unnormalized form around (and emit a lint warning?))
    • or whether we want to refrain from normalizing away "paths" (const aliases/projections is the proper term) referring to public const items similar to type aliases (which is based on rustdoc's IR "clean AST")). Whether that's even possible to do (custom normalization logic) if we have a MIR const or a ValTree assuming we want to throw out our "clean AST"-based normalization logic for good. Etc etc.

Footnotes

  1. This comes up with assoc consts that normally don't get eval'ed if not referenced. ↩

Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
- Feature Name: `doc_consts`
- Start Date: 2025-01-20
- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000)
- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000)
- Pre-RFC: [Pre-RFC: `#[doc(consts)]` attribute](https://internals.rust-lang.org/t/pre-rfc-doc-consts-attribute/21987)

# Summary
[summary]: #summary

Introduce a `#[doc(normalize::consts = ...)]` attribute controlling how constant expressions are rendered by rustdoc.

# Motivation
[motivation]: #motivation

Different crates and items have conflicting requirements for their constants.
For some, [the exact value of a constant is platform dependant](https://internals.rust-lang.org/t/pre-rfc-doc-consts-attribute/21987/9).
For others, [constant folding obsurces the meaning of values](https://github.com/rust-lang/rust/issues/128347).
Hovever, [showing a constant as written may leak implementation details],
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is there a link missing here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, it's one of the linked issues in rust-lang/rust#99688 (i'll go dig through it in a bit)

and in some cases, there is no possible value that would be meaningful to the user of the library.


# Guide-level explanation
[guide-level-explanation]: #guide-level-explanation

The `#[doc(normalize::consts)]` attribute can be placed on any item to control how contained constant expressions are displayed in rustdoc-generated documentation.

* `#[doc(normalize::consts = "fold")]` will show them in their fully-evaluated state.
* `#[doc(normalize::consts = "expr")]` will show them as-written.
* `#[doc(normalize::consts = "hide")]` will cause constant expressions to be replaced with `_` or not shown at all.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why use the qualified name syntax rather than something more normal (😉) like

#[doc(normalize(consts = "expr", types = "hide"))]
static X: [SomeComplicatedType; 123456] = evaluate_lookup_table(include_bytes!("lookup.bin"));

// or

#[doc(normalize_consts = "expr")]
#[doc(normalize_types = "hide")]
static X: [SomeComplicatedType; 123456] = evaluate_lookup_table(include_bytes!("lookup.bin"));

AFAIK in an attribute the x::y syntax is only1 used for "tool attributes" #[rustfmt::skip] and "tool lints" #[warn(clippy::pedantic)], and normalize here is certainly not a "tool".

Footnotes

  1. unless when that x::y is used to refer to an item like in #[cfg(accessible(x::y))], of course ↩

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the diagnostic namespace exists. also this isn't a full attribute, it's an argument to the doc attribute.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes and clippy, rustfmt, diagnostic, miri, rust_analyzer are all regarded as "tools".

The point is the x::y syntax appearing in built-in Rust attributes only as

  1. tool attributes/lints
  2. #[cfg(accessible(crate::item))]
  3. #[instruction_set(arm::a32)] / #[instruction_set(arm::t32)]

#[doc(normalize::consts)] fit into neither category, so this RFC is introducing a 4th item. Comparing to the existing three:

  1. for tool attributes/lints, it is natural to assign each tool into its own "namespace", and the namespace is extensible outside of the Rust Team's control (clippy, rustfmt, etc.)
  2. for cfg_accessible, the path syntax is just natural
  3. for instruction_set, it is also natural1 to use the architecture name as the "namespace" to group the sub-instruction-sets, and again the namespace is extensible (arm, mips, etc.) in a way not dictated by the Rust.

In this RFC there's nothing suggests normalize needs to be namespace-like. There is not a second #[doc(something::a = "b")] similar to #[doc(normalize::x = "y")] in terms of categorization. The handling of #[doc(...)] is managed by wholly by rustdoc, there is no 3rd party involvement. There is no argument why non-namespaced syntax like #[doc(normalize(x = "y"))] is sub-optimal. (Also I don't see anywhere in @fmease's comment suggesting turning normalize into a prefix, they is just suggesting to consider normalization of types as well.)

In summary, pivoting to #[doc(normalize::consts = "fold")] is an abuse of syntax for zero good reasons. 👎.

Footnotes

  1. though I'd argue that this is not really a good syntax to specify the instruction set, as RFC: Add a new #[instruction_set(...)] attribute for supporting per-function instruction set changes #2867 suggested the feature may be extended to support 65c02 mode in 65c816, if Rust ever gained support of it, but both 65c816 and 65c02 aren't valid identifiers (the llvm-mos project calls the architecture "mos" so it's not an actual issue). ↩

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I simply believe that the nested function call syntax is less readable, and like you said, rustdoc has complete control over the doc( attribute syntax, so why not use the more readable syntax?

Personally, I would've preferred if all doc( attributes were instead written as doc::, I think that would've made more sense.

I think instruction_set actually acts as pretty good precedence for this, after all, it could've easily been written as #[instruction_set(arm(a32))].

I think I'll wait for a third party to weigh in before changing the proposed syntax again.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I simply believe that the nested function call syntax is less readable, and like you said, rustdoc has complete control over the doc( attribute syntax, so why not use the more readable syntax?

I just don't see how #[doc(normalize::consts = "x")] is any more readable then #[doc(normalize_consts = "x")]. Even #[doc(normalize(consts = "x"))] is not really that bad as the nesting must be limited at level 2, unlike #![doc(test(attr(deny(dead_code))))].

The slight advantage of the nested syntax is allowing the two normalization instructions grouped into a single attribute, #[doc(normalize(consts = "x", types = "y"))], but breaking it into 2 lines #[doc(normalize_consts = "x")] #[doc(normalize_types = "y")] isn't really a big disadvantage IMO.

I think instruction_set actually acts as pretty good precedence for this, after all, it could've easily been written as #[instruction_set(arm(a32))].

#2867 starts out as #[instruction_set(a32)], the arm namespace was added on later for disambiguation.

The original suggestion was #[instruction_set(arm_a32)] (not the "real name", thus hurts searchability) and then #[instruction_set(arm, a32)] (does not suggest a hierarchical relationship).

None of the arguments are relevant to normalize::consts / normalize::types.

Copy link
Member

@fmease fmease Jun 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added a normalize:: prefix, what do you think about that?

Sorry for the late reply. Thanks for incorporating my suggestion/concern/point about types! At this stage of the process, I will refrain from thinking too much about syntax choices because I deem it a bit too early.

However I do agree with kennytm that #[a(b::c = d)] looks quite particular for lack of a better word due to the mixing of "legacy namespacing" a(b) and modern namespacing a::b. Drawing a comparison to the diagnostic tool namespace is slightly misguided I would say since it presumably would not actually leverage rustc_resolve's ToolMod logic.

I think I'll wait for a third party to weigh in before changing the proposed syntax again.

Anyhow, please don't feel the need to change the syntax again, it's too early to paint the shed, I'd like to focus on more pressing things first.

Copy link
Contributor Author

@lolbinarycat lolbinarycat Jun 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can understand the position that we should just commit to our decisions, even if they're slightly unoptimal.

What things do you think are more pressing and need addressing?

EDIT: saw your other comment



# Reference-level explanation
[reference-level-explanation]: #reference-level-explanation


## The Attribute
The `#[doc(normalize::consts)]` attribute determines how constant expressions (constexprs) are rendered by rustdoc.
When applied to any item (including the top-level module within a crate, or impl blocks), it affects all constexprs within that item, and within all childern of that item.
Whenever multiple such attributes would take effect, the innermost attribute takes priority.

constexprs affected include:
* the RHS of `const` items
* the RHS of `static` items
* const generics in type aliases

### Interaction with `#[doc(inline)]`
When an item is inlined, it is rendered as if it had been defined in the crate it is being inlined into.

This means that if the `doc(normalize::consts)` modes of the source and destination crate do not match, an inlined item will *always* be rendered with the mode from the destination crate.

## The Values

### "fold"
The current default. Rustdoc will evaluate the constexpr and print it in its fully evaluated form, as if the constexpr was written as a literal.

Numbers will be printed in base 10.

### "expr"
Rustdoc will print the constexpr as-written.

If the constexpr contains private identifiers, they will be exposed, so library authors should take care when using this mode.

### "hide"
This will cause constants and statics to display without any value, as if the value was unrenderable (see [ONCE_INIT](https://doc.rust-lang.org/nightly/std/sync/constant.ONCE_INIT.html)), and will cause other constant expressions–such as generic const parameters–to be rendered as `_`.

<!--This is the technical portion of the RFC. Explain the design in sufficient detail that:

- Its interaction with other features is clear.
- It is reasonably clear how the feature would be implemented.
- Corner cases are dissected by example.

The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work. -->

# Drawbacks
[drawbacks]: #drawbacks

Rustdoc does not currently have the ability to show all constants as-written, namely in the case of inlined re-exports from other crates.

# Rationale and alternatives
[rationale-and-alternatives]: #rationale-and-alternatives

* The attribute is named `consts` and not `const` to avoid using keywords in attributes
* A key-value format is used instead of a directive system like `doc(fold)` to allow multiple states without polluting the doc attribute namespace.
* The `normalize::` prefix is used because of how const normalization paralells type normalization,
and to improve discoverability via search engines if someone finds it in an unfamiliar codebase.
<!--
- Why is this design the best in the space of possible designs?
- What other designs have been considered and what is the rationale for not choosing them?
- What is the impact of not doing this?
- If this is a language proposal, could this be done in a library or macro instead? Does the proposed change make Rust code easier or harder to read, understand, and maintain?
-->
# Prior art
[prior-art]: #prior-art

- [RFC 3631](https://github.com/rust-lang/rfcs/pull/3631) for an attribute that affects the rendering of child items in a nesting way.

<!--- For language, library, cargo, tools, and compiler proposals: Does this feature exist in other programming languages and what experience have their community had?
- For community proposals: Is this done by some other community and what were their experiences with it?
- For other teams: What lessons can we learn from what other communities have done here?
- Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to, this can serve as a more detailed theoretical background.

This section is intended to encourage you as an author to think about the lessons from other languages, provide readers of your RFC with a fuller picture.
If there is no prior art, that is fine - your ideas are interesting to us whether they are brand new or if it is an adaptation from other languages.

Note that while precedent set by other languages is some motivation, it does not on its own motivate an RFC.
Please also take into consideration that rust sometimes intentionally diverges from common language features.-->

# Unresolved questions
[unresolved-questions]: #unresolved-questions

- What should be happen rustdoc cannot format a constant as requested?
- How should structs be handled in `"expr"` mode?
- Are there any other constants that show up in items that this should affect?
- How desirable is the hiding of generic const parameters?
<!--
- What parts of the design do you expect to resolve through the RFC process before this gets merged?
- What parts of the design do you expect to resolve through the implementation of this feature before stabilization?
- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC?
-->

# Future possibilities
[future-possibilities]: #future-possibilities

- `#[doc(normalize::types)]` to control normalization of types.
- Controlling the base of folded integer literals.
- Allowing the attribute on individual constant expressions, such as if a type alias has multible const generics that should be rendered differntly.
- Seperatly specifying the rendering for different categories of constant expressions, such as declaring that only `static` items should have their value hidden.
- Control formatting of expression (collapsing/adding whitespace, etc.)

<!--Think about what the natural extension and evolution of your proposal would
be and how it would affect the language and project as a whole in a holistic
way. Try to use this section as a tool to more fully consider all possible
interactions with the project and language in your proposal.
Also consider how this all fits into the roadmap for the project
and of the relevant sub-team.

This is also a good place to "dump ideas", if they are out of scope for the
RFC you are writing but otherwise related.

If you have tried and cannot think of any future possibilities,
you may simply state that you cannot think of anything.

Note that having something written down in the future-possibilities section
is not a reason to accept the current or a future RFC; such notes should be
in the section on motivation or rationale in this or subsequent RFCs.
The section merely provides additional information. -->