Document that `Debug` output of structures is unstable

[rivy]

Pretty printed structures for cfg!(windows) have trailing commas, which is inconsistent with the debug output format documentation and output on non-windows platforms.

use std::fmt;
struct Foo { bar: u32, baz: Option<u32> }
impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
        fmt.debug_struct("Foo")
           .field("bar", &self.bar)
           .field("baz", &self.baz)
           .finish()
    }
}
fn main() {
    let cfg_windows = if cfg!(windows) { "true" } else { "false" };
    let foo = Foo { bar: 1, baz: Some(1) };
    println!("[cfg!(windows) == {}]\n{:?}\n{:#?}", cfg_windows, foo, foo);
}

C:> rustc --version
rustc 1.36.0 (a53f9df32 2019-07-03)
C:> cargo run
   Compiling t-debug_struct v0.1.0 (C:\Users\Roy\OneDrive\Projects\rust\t-debug_struct)
    Finished dev [unoptimized + debuginfo] target(s) in 0.53s
     Running `target\debug\t-debug_struct.exe`
[cfg!(windows) == true]
Foo { bar: 1, baz: Some(1) }
Foo {
    bar: 1,
    baz: Some(
        1,
    ),
}

$ rustc --version
rustc 1.33.0 (2aa4c46cf 2019-02-28)
$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/t-debug_struct`
[cfg!(windows) == false]
Foo { bar: 1, baz: Some(1) }
Foo {
    bar: 1,
    baz: Some(
        1
    )
}

[CryZe]

Isn't the formatting of Debug implementations (at least the derived ones) considered an implementation detail and you shouldn't be testing against those?

Also you seem to be using an outdated compiler on Linux. The formatting changed to include the commas and it does so for me on Linux as well:

[cfg!(windows) == false]
Foo { bar: 1, baz: Some(1) }
Foo {
    bar: 1,
    baz: Some(
        1,
    ),
}

[RalfJung]

@rivy could you do rustc --version on both platforms to check that you are using the same compiler version?

[rivy]

I was using fairly recent version of rustc for both (1.36.0 [2019-07-03] and v1.33.0 [2019-02-28], respectively). I've inserted the version output into the original issue statement.

I ran across this while trying to fix some failing windows tests for "ansi-term".

I've fixed that by converting to a regex comparison with optional trailing commas. So, that issue is essentially solved. And, I'm just fine if it's an "implementation detail" and subject to change, but that's not mentioned anywhere within the usual documentation that I could find.

Pretty-print seems to be a convenient way to compare structures visually, so, I suspect that others are using it for comparisons. A mention in the official documentation about what can be expected to remain stable and what might change would be helpful.

[RalfJung]

1.36.0 [2019-07-03] and v1.33.0 [2019-02-28]

That would explain the difference then. Could you adjust the issue title? This has nothing to do with Windows vs non-Windows. The output simply changed between two versions.

[rivy]

Yes, you're correct. The pretty-print is differing between versions, not platforms. It's the same, per platform, when using the same rustc version.

Since at least the ansi-term package is using the pretty-print to compare structures, I think it'd be a good idea to make a notation in the official documentation about stability and/or instability of the pretty-print output.

Also, any recommendations for structural comparison during testing?

I'd like to give @ogham a PR for a better way to test his structure (see https://github.com/ogham/rust-ansi-term/blob/master/src/debug.rs#L104-L122). I've already supplied a regex comparison which fixes the specific trailing-comma / no-trailing-comma problem (see ogham/rust-ansi-term#52), but that seems quite fragile if pretty-print has no output guarantees.

[rivy]

Thanks for the input @CryZe and @RalfJung!