Someone who decided to look at some documentation for my Rust code saw // some fields omitted and was confused and thought that there was something broken with rustdoc being unable to display some fields. I had to explain to him that it was because it was some fields were private but he pointed out that had nothing to do with the API. In response I pointed out that it does affect whether you are able to create instances of that struct outside of that module and he countered that the comment should instead say that directly such as // cannot instantiate directly.
Thoughts?
// private fields omitted?
Beyond just construction, it also effects unsafe manipulations like transmute, as well as destructuring:
mod foo {
pub struct Baz{
a: uint,
pub b: uint,
}
pub fn make_baz() -> Baz{
Baz { a: 0, b: 1 }
}
}
mod bar {
use foo;
fn main () {
let baz = foo::make_baz();
//must omit a value, because there's more, but we can't reference them
let foo::Baz { b, .. } = baz;
println!("{}", b);
}
}
2 Likes
Perhaps something like // ... ?
Like Gankro said, perhaps simply stating that the omitted fields are private // private fields omitted
Made a PR since it’s a super-minor change, and can be bikeshedded there if necessary: https://github.com/rust-lang/rust/pull/16376
Conclusion for those that didn’t follow along: Fields can be omitted by the docs either because they’re private, or because they’re suppressed by an annotation (possibly more ways?). Thus, // some fields omitted is truly the most accurate note, as the fields need not be private, and the object can be instantiable directly.
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.