From 81ca826b56463219e4f04c8ff3f26cf256b5014d Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Sat, 25 Jan 2025 13:35:42 -0600
Subject: [PATCH 1/3] begin work on #[doc(consts)] rfc

---
 text/0000-doc-consts.md | 134 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 text/0000-doc-consts.md

diff --git a/text/0000-doc-consts.md b/text/0000-doc-consts.md
new file mode 100644
index 00000000000..609498ef928
--- /dev/null
+++ b/text/0000-doc-consts.md
@@ -0,0 +1,134 @@
+- 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(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], 
+and in some cases, there is no possible value 
+
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+The `#[doc(consts)]` attribute can be placed on any item to control how contained constant expressions are displayed in rustdoc-generated documentation.
+
+* `#[doc(consts = "fold")]` will show them in their fully-evaluated state.
+* `#[doc(consts = "expr")]` will show them as-written
+* `#[doc(consts = "hide")]` will cause constant expressions to be replaced with `_` or not shown at all.
+
+
+# Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+
+## The Attribute
+The `#[doc(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
+
+## 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
+
+- 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?
+
+<!--
+- 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
+
+- 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. -->

From 701de89d7e2323a179a28a47bd937f3d7abf1d71 Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Mon, 10 Feb 2025 15:37:40 -0600
Subject: [PATCH 2/3] provide rationale, expand edge cases and unresolved
 questions

---
 text/0000-doc-consts.md | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/text/0000-doc-consts.md b/text/0000-doc-consts.md
index 609498ef928..5b058b32326 100644
--- a/text/0000-doc-consts.md
+++ b/text/0000-doc-consts.md
@@ -16,7 +16,7 @@ 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], 
-and in some cases, there is no possible value 
+and in some cases, there is no possible value that would be meaningful to the user of the library.
 
 
 # Guide-level explanation
@@ -25,7 +25,7 @@ and in some cases, there is no possible value
 The `#[doc(consts)]` attribute can be placed on any item to control how contained constant expressions are displayed in rustdoc-generated documentation.
 
 * `#[doc(consts = "fold")]` will show them in their fully-evaluated state.
-* `#[doc(consts = "expr")]` will show them as-written
+* `#[doc(consts = "expr")]` will show them as-written.
 * `#[doc(consts = "hide")]` will cause constant expressions to be replaced with `_` or not shown at all.
 
 
@@ -43,6 +43,11 @@ constexprs affected include:
 * 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(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"
@@ -57,6 +62,7 @@ If the constexpr contains private identifiers, they will be exposed, so library
 
 ### "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.
@@ -73,11 +79,15 @@ Rustdoc does not currently have the ability to show all constants as-written, na
 # 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.
+
+<!--
 - 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
 
@@ -100,7 +110,8 @@ Please also take into consideration that rust sometimes intentionally diverges f
 
 - 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?

From 735fc4b9ee982f66f52f7abdda7ffdbd118351bd Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Tue, 27 May 2025 16:08:57 -0500
Subject: [PATCH 3/3] add normalize:: prefix

---
 text/0000-doc-consts.md | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/text/0000-doc-consts.md b/text/0000-doc-consts.md
index 5b058b32326..893485976b4 100644
--- a/text/0000-doc-consts.md
+++ b/text/0000-doc-consts.md
@@ -7,7 +7,7 @@
 # Summary
 [summary]: #summary
 
-Introduce a `#[doc(consts = ...)]` attribute controlling how constant expressions are rendered by rustdoc.
+Introduce a `#[doc(normalize::consts = ...)]` attribute controlling how constant expressions are rendered by rustdoc.
 
 # Motivation
 [motivation]: #motivation
@@ -22,11 +22,11 @@ and in some cases, there is no possible value that would be meaningful to the us
 # Guide-level explanation
 [guide-level-explanation]: #guide-level-explanation
 
-The `#[doc(consts)]` attribute can be placed on any item to control how contained constant expressions are displayed in rustdoc-generated documentation.
+The `#[doc(normalize::consts)]` attribute can be placed on any item to control how contained constant expressions are displayed in rustdoc-generated documentation.
 
-* `#[doc(consts = "fold")]` will show them in their fully-evaluated state.
-* `#[doc(consts = "expr")]` will show them as-written.
-* `#[doc(consts = "hide")]` will cause constant expressions to be replaced with `_` or not shown at all.
+* `#[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.
 
 
 # Reference-level explanation
@@ -34,7 +34,7 @@ The `#[doc(consts)]` attribute can be placed on any item to control how containe
 
 
 ## The Attribute
-The `#[doc(consts)]` attribute determines how constant expressions (constexprs) are rendered by rustdoc.
+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.
 
@@ -46,7 +46,7 @@ constexprs affected include:
 ### 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(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.
+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
 
@@ -81,7 +81,8 @@ Rustdoc does not currently have the ability to show all constants as-written, na
 
 * 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?
@@ -91,7 +92,6 @@ Rustdoc does not currently have the ability to show all constants as-written, na
 # 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?
@@ -121,6 +121,7 @@ Please also take into consideration that rust sometimes intentionally diverges f
 # 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.