Clarify why fields are omitted in docs

[Gankro]

In response to: http://discuss.rust-lang.org/t/some-fields-omitted/357

[lilyball]

The wording "private fields omitted" just feels vaguely tautological to me. I mean, they're private, which pretty much by definition means they're not part of the API, so it's basically like saying "omitted fields omitted".

[Gankro]

To someone new to the language (which our docs should be friendly to!), it might be unclear that being private is the only reason to have the fields omitted from the documentation. This makes it simple and explicit.

[lilyball]

@Gankro So far, this is an anecdote about a single person who was new to the language who didn't realize what something meant. Hardly enough data to make any changes over. Personally, I feel that "private fields omitted" just sounds wrong. It makes me want to say "yes rustdoc, that's what private fields do, thanks for telling me".

[sfackler]

I intentionally chose the language "some fields" instead of "private fields" because there are cases other than privacy for which rustdoc will omit a field, e.g. struct Foo { #[doc(hidden)] pub foo: int, }.

[Gankro]

@sfackler ah! Okay then. Although... why would you do this? To have pseudo-privates...?

[sfackler]

One of the main use cases is to make types that are instantiatable by syntax extensions like this: https://github.com/sfackler/rust-phf/blob/master/phf/src/lib.rs#L45-L54

[Gankro]

Yep, basically what I was picturing. Sounds good. Closing it up.