Change struct rendering to include a case for all fields being omitted

[coder543]

The Path documentation provides a good case-in-point. The struct for Path is being rendered as

pub struct Path {
    // some fields omitted
}

when it could be rendered as

pub struct Path {
    // all fields omitted
}

since there are no fields which have not been emitted. It just feels like an understatement when it says "some" fields have been omitted, and there are no fields being shown at all.

[bugaevc]

Why not "private fields omitted"? It may be confusing to somebody new ("why are they omitting some/all fields?")

[abonander]

@bugaevc has a good point, though one (weak) counterpoint is pub fields annotated with #[doc(hidden)], which Rustdoc will treat as private but the compiler will still allow access to (necessary for the implementation details of some macros).

However, since hidden fields are effectively private to most API users, I don't think they necessitate a different wording, especially since those who know enough to know the difference won't shouldn't be confused by it.

[bugaevc]

When there are hidden fields, we may want to go with "private and hidden fields omitted", if it's worth it.

[ollie27]

I've uploaded an alternative which just renders { .. } for completely opaque structs: #35667.

[bugaevc]

I've uploaded an alternative which just renders { .. } for completely opaque structs: #34713.

You've linked to this very issue ;) The correct link is #35667

[ollie27]

oops, my bad, thanks

[bugaevc]

My proposal

Why not "private fields omitted"? It may be confusing to somebody new ("why are they omitting some/all fields?")

stays if your alternative gets merged, for partly opaque structs.

By the way, are they a common thing? Are there statistics for stdlib & crates.io?

[ollie27]

I think the only instance in std is std::process::Child so I don't think they're very common at all.

I guess we could also change "some fields omitted" to "private fields omitted" or "private/hidden fields omitted". There's also "some variants omitted" on enums although in that case it's only from #[doc(hidden)]: std::io::ErrorKind.

[bugaevc]

A bit off-topic: is there a reason why these prototypes are not syntax-highlighted?

[steveklabnik]

Triage: this now says fields omitted, which works in both cases. Closing!