#[doc(consts)] #3770
#[doc(consts)] #3770
Conversation
fmease
added
the
T-rustdoc
|
|
||
| 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. |
There was a problem hiding this comment.
how about "eval" for fully evaluated item and "as-is" for item as written?
There was a problem hiding this comment.
"constant folding" is a well established term used for this exact process, and "eval" is much more general (future display modes would likely also involve evaluating the expression).
on the other hand, i don't feel strongly about "expr", but my second choice would probably be "verbatim".
There was a problem hiding this comment.
Does Rust ever refer to CTFE as constant folding? The docs use evaluation https://doc.rust-lang.org/reference/const_eval.html, and to me "const folding" is an identify+transform optimization pass (as opposed to compile-time evaluation that must unconditionally be run).
| 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], |
There was a problem hiding this comment.
yes, it's one of the linked issues in rust-lang/rust#99688 (i'll go dig through it in a bit)
Rendered