Rustdoc does not evaluate array length expressions

[Osspial]

Summary

When rustdoc creates documentation for a struct/enum with an array as one of the fields, the expression for array length is not evaluated, leading to less clear documentation. For example, take this struct Foo:

pub struct Foo(pub [i32; 7 + 1]);

One might expect that rustdoc would produce documentation along the lines of this:

pub struct Foo(pub [i32; 8]);

Instead, it produces this:

This might not immediately appear to be an issue - for example, it would be best for arrays with lengths defned as const values plus another value (e.g. BAR + 1) to have rustdoc output BAR + 1. However, it becomes much more of an issue when a programmer begins using macros. Take the following:

macro_rules! new_foo {
    ($arr_len_minus_one:expr) => {
        pub struct Foo(pub [i32; $arr_len_minus_one + 1]);
    }
}

new_foo!(7);

One would expect that rustdoc would transform $arr_len_minus_one into 7, but instead the following is output:

It is impossible to discover the length of the array without looking at the source code. However, it can get far worse than that. Let's say the macro takes a series of identifiers (perhaps for an initialization function) and creates an array with a length determined by the number of identifiers given:

macro_rules! count { 
    ($foo:tt) => (1); 
    ($($element:tt),*) => {{$(count!($element) +)* 0}}; 
} 

macro_rules! new_foo {
    ($($field:ident),+) => {
        pub struct Foo(pub [i32; count!($($field),+)]);
    }
}

new_foo!(a, b, c, d, e, f, g);

In this case, the documentation looks like this:

That's unreadable even if you know how the code works - it's borderline impossible if these are macros that are only used internally to the library and aren't as documented as well as they could be. Even if rustdoc were to collapse the invocation down to an actual, macro-less expression the documentation would still look like this:

pub struct Foo(pub [i32; 1 + 1 + 1 + 1 + 1 + 1 + 1]);

That's a bit more readable, but isn't anywhere near conveying the number of elements in an array at a glance, which is what documentation is supposed to do. Instead, rustdoc should aim to evaluate the expression giving the length of an arrray, like so:

pub struct Foo(pub [i32; 7]);

In the event that the array length involves some constant value, rustdoc should instead attempt to fully simplify the expression, turning this:

pub const BAR: usize = 10;

pub struct Foo(pub [i32; BAR + 7 + 3]);

into this:

pub struct Foo(pub [i32; BAR + 10]);

Meta

rustc 1.9.0 (e4e8b6668 2016-05-18)
binary: rustc
commit-hash: e4e8b666850a763fdf1c3c2c142856ab51e32779
commit-date: 2016-05-18
host: x86_64-unknown-linux-gnu
release: 1.9.0

[jethrogb]

I'm not sure what part of this issue was fixed by #34684 and what problems might still exist. cc @oli-obk

[oli-obk]

My changes fully evaluate array length, so there are no more constants left, but just a number.

[QuietMisdreavus]

Update: rustdoc now completely evaluates array lengths out before printing, so all of the samples in the issue description now work properly. The one possible exception was the offhand BAR + 1, which it doesn't preserve:

However, that still leaves a usable definition, so i'm closing this issue.