bitflags!-generated public API has poor documentation UX

[sfackler]

Say I'm at the documentation page for std::io::fs::mkdir and want to figure out how to call it: http://doc.rust-lang.org/std/io/fs/fn.mkdir.html. I want to figure out what the FilePermission type is, so I click on the link to its docs. I get sent here: http://doc.rust-lang.org/std/io/struct.FilePermission.html. Unfortunately, that page gives no indication at all of how actually initialize a FilePermission in a useful way. I have to somehow divine that I need to jump out to the documentation for the io module and scroll all the way to the bottom to the constants section: http://doc.rust-lang.org/std/io/index.html#constants to actually find some useful values to pass to mkdir.

Associated constants would help with this, as would sufficient compiler support to implement a robust EnumSet.

[aturon]

cc @bjz

[sfackler]

EnumSet seems cleaner to me personally, but the usability wouldn't be as nice unless we could make MyEnum::Foo | MyEnum::Bar turn into EnumSet<MyEnum>.

[aturon]

We could potentially hack this without associated constants by providing constructor functions corresponding to each constant. But that's pretty ugly.

My recollection is that EnumSet suffered from other usability problems in terms of coding in a C-like style with the flags, but it's been a long time since I looked at it.

[aturon]

Hah, @sfackler beat me to it. :-)

[sfackler]

We could also define EnumSet::of([Foo, Bar]), assuming C-like enums are Copy. It's a bit more Java-like than C-like but not too bad.

[steveklabnik]

Triage: the motivating example is gone, but i'm guessing the issue still persists.

[sfackler]

The bitflags macro has been pulled out to a separate crate, so this issue can probably be migrated: http://doc.rust-lang.org/rustc_bitflags/macro.bitflags!.html

[sfackler]

cc @nick29581

[steveklabnik]

http://doc.rust-lang.org/bitflags/bitflags/index.html is the new link, and yeah, this still persists. Not moving because this will still affect any user macro docs, but removing a-libs since this is really just a rustdoc issue.

[steveklabnik]

This is actually a dup of #17616

[durka]

@steveklabnik not a dupe. The motivating example was this I guess, whereas #17616 is about rustdocking the macro itself.