Verbose Documentation for the number types

documentation
1

It would be helpful to add a little more information about the number type(s) in the rust documentation. In the current documentation which is accessible via rust-analyzer, if I were to hover over the u16 type label it would show u16 The 16-bit unsigned integer type. It may be nicer if it would show:

u16
The 16-bit unsigned integer type.
Can hold values from 0 to 65,535.

Similarly, for i32

i32
The 32-bit signed integer type.
Can hold values from -2,147,483,648 to 2,147,483,647
2

I think writing out the decimal numbers is overly noisy.

Maybe having "0..2¹⁶" and "-2³¹..2³¹", though?

1 Like
3

But isn't that implied from the bit count?

4

Yes. This is a classic Learnability vs Efficiency (term definitions) problem.

If you're new, you want all these details every time because you don't know them yet. If you're not, you don't want them because of course that's what a signed number means.

That's why we have --explain for rustc errors even though experienced people (approximately) never use it, for example.

What's the right balance here? No idea.

3 Likes
5

I also wanted primitive types to show their size and their alignment on different targets, e.g. a prettier version of:

/// has size 8.
/// | target | alignment |
/// |-|-|
/// | x86_64-unknown-linux-gnu | 8 |
/// | i686-unknown-linux-gnu | 4 |
/// | ... | ... |
impl f64 {
    ...
}
6

Should there be a cargo configuration or envvar that implies --explain for new users? Perhaps possible to set up with cargo config --i-am-new-here (subject to bikeshedding)?