provide detailed documentation of entry API

[Gankra]

Also added some re-exports that were missing from btree that this exposed.

[alexcrichton]

It seems unfortunate to duplicate the documentation across these two functions, perhaps the philosophy behind the Entry-based API could be outlined in std::collections documentation and these two functions could refer to that? The idea is to expand this API to more collections, right?

[Gankra]

@alexcrichton Yeah, I wasn't sure on this. Where would it go in collections?

One possibility is to make the Entry enum generic and part of libcollections, and have each Map share it. Then the docs could reasonably go there?

This will also be a problem when we start axing the collection traits. So maybe we need to figure out a more robust solution for this.

[alexcrichton]

Hm, I was thinking of perhaps the module documentation for std::collections, but that's also a bit of an odd place. Another option would possibly be just linking the btree documentation for entry to the hashmap documentation for entry?

[Gankra]

cc @steveklabnik @aturon

[aturon]

Yeah, this is one of the downsides of not using traits for common interfaces (which of course we want to eventually).

Personally, I like the idea of beefing up the docs for std::collections -- we can incorporate whatever conventions and patterns come out of collections reform/stabilization, as well as the Entry API. The doc comments on the Entry types and individual entry methods can then be kept short, with a pointer to the main doc.

[Gankra]

@aturon So you would just have it floating loose on this page? http://doc.rust-lang.org/std/collections/

[aturon]

@gankro Yes, exactly. Right now there's literally no documentation for this module, and I think it would be great to instead provide an overview of the APIs, including Entry. (This would be a good place for the performance overview to go, for example.)

[Gankra]

@aturon Yes, but I remember we nixed doing that for... a reason. What were we waiting for? Stabalization?

[aturon]

@gankro I think the hesitation before was mainly that it didn't make sense to land just the performance overview, without a more general overview of the API surface. (This was aside from issues about the perf stuff being too much of a tutorial on asymptotics.)

Anyway, it would be really great to start work on a solid overview of the collections, both in terms of the concrete collections and their tradeoffs, and in terms of the most significant APIs/conventions. Might be good to coordinate with @steveklabnik. Is that something you'd be interested in working on?

[Gankra]

Closing in favour of #17802