rustdoc: Named constants in array sizes shouldn't be evaluated

[jmillikin]

Current rustdoc behavior

Given the following code:

pub struct SomeStruct { _p: () }

#[cfg(target_os = "linux")]
const TARGET_STORAGE_SIZE: usize = 128;
#[cfg(not(target_os = "linux"))]
const TARGET_STORAGE_SIZE: usize = 256;

impl SomeStruct {
    /// How much storage to allocate for a call to
    /// [`some_method`](Self::some_method).
    pub const STORAGE_SIZE: usize = TARGET_STORAGE_SIZE;

    /// The user is expected to call this with an array of size
    /// `SomeStruct::STORAGE_SIZE`, whatever that happens to be.
    pub fn some_method(
        &self,
        storage: &mut [u8; SomeStruct::STORAGE_SIZE],
    ) {}
}

The user would be expected to call it like this:

let mut storage = [0u8; SomeStruct::STORAGE_SIZE];
some_struct.some_method(&mut storage);

Unfortunately, the rustdoc output is confusing because it evaluates the constant when formatting the function signature:

If a user were to copy-paste from the rustdoc'd function signature when writing the call site, they would write code like this, which would fail to compile on some platforms:

let mut storage = [0u8; 128];
some_struct.some_method(&mut storage);

Proposed new behavior

A better way to format this function signature would be to use the constant's name, if the constant is public:

An even niftier formatting would let the constant become a link:

[fmease]

This strongly relates to the ongoing discussion around the formatting of constant values and expressions in rustdoc. I am in the process of writing an RFC (I've finally found time to start working on it). Your issue would fit in the drawbacks / alternatives section.

I won't assign myself to this issue since I am already assigned to too many issues related to this topic and no decisions have been reached yet and everything is very much in flux, hence the planned RFC.

See also: Zulip discussion, #98929

[fmease]

Part of https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/new.20const.20display/near/364308963

@rustbot claim

[JohnScience]

Agreed.