Pre-RFC: `#[doc(consts)]` attribute

1

This attribute would control how various constant expressions are displayed in documentation, such as values of generic const parameters, C-style enum discriminants, and the RHS of static and const items. It would also apply to the default value of struct fields, if/when those are implemented.

It could appear on any item (module, struct, impl block, etc.) and would affect that item and any nested items (note that to affect associated items of a struct, you need to tag the impl block). The innermost #[doc(consts)] attribute would take priority, allowing you to set a full-crate default and then override it for specific items or modules.

There are three main values for it (names subject to bikeshedding):

  • "fold": show constants in their fully evaluated form
  • "expr": show constants as-written
  • "hide": do not show constants, replacing them with _

Future possibilities include a fold_hex value to display integer constants in hexadecimal.

19 Likes
2

I like this idea. It lets documentation authors control a sometimes-important part of their documentation, where they are currently stuck with rustdoc having exactly one behavior (which sometimes exposes implementation details). All three options are appropriate in different situations.

8 Likes
3

Sounds like a nice idea, but what would be the semver semantics of the three variants?

4

Semver semantics of constant expressions isn't decided in general

https://doc.rust-lang.org/cargo/reference/semver.html

1 Like
5

And how do you propose it should work for your proposed feature? Or are your saying you want to avoid taking a stance?

The main reason for me to use this feature would be the semver implications of hiding the values.

6

I believe the default interpretation is "everything not in the documentation is semver-excempt", with a few explicit exceptions, such as lifetime variance.

Lack of formal guidelines for semver comparability is a separate issue, and should be addressed separately (ideally, each library would document guarantees for what it considers a breaking change, but we do not live in an ideal world)

This issue can be worked around by crates that use this attribute for semver compatibility reasons having a line in their documentation that the values of hidden constant expressions are semver exempt.

3 Likes
7

Rustdoc could probably just display all forms at the same time.

8

no. the entire reason this is a discussion is that rustdoc used to show constants as-written, but that was changed because it was leaking implementation details.

1 Like
9

Yes please. Look at this nonsense:

image
image727×154 17 KB

I wish it would just show usize::MAX >> 3 instead of this random platform-specific value.

7 Likes
10

I don't think I'd call it "random", but knowing that it is different on 32-bit platforms is quite relevant.

1 Like
11

That also looks like a place where it'd be nice to have some heuristics about whether to show hex or not.

Seeing 0x1FFF_FFFF_FFFF_FFFF is way more helpful than 2305843009213693951.

12

This is still less useful than knowing it is usize::MAX >> 3 here because even the hex value is a lie if I'm looking at docs.rs but developing for a 32bit platform. I think this is really best if it is author-controlled rather than working around heuristics.

6 Likes
13

I'd also like to see something similar for type aliases.

I've written primitive type aliaes where the exact rhs isn't super important (or portable).

2 Likes
14

Is this something that needs an RFC (seems like it to me)? Anyone want to draft one up? I might be able to help with some implementation and/or review (I've done some attribute stuff in rustc before, but it has been a while).

15

This would likely be beneficial to rust-analyzer as well, which currently renders the following the MAX_PERMITS example on hover:

const MAX_PERMITS: usize = 18446744073709551608 (0xFFFFFFFFFFFFFFF8)

Where as such a doc attribute could influence the rendering for rust-analyzer alike.

3 Likes