Trait crates: Automatically list users and implementers

[chrysn]

Right now, while we provide links to crates roughly structured into "implements embedded-hal" and "uses embedded-hal" (driver crates). For the crates we list, that's easily managed manually, and we only list awesome stuff and that determination can not be made automatically yet.

The utility of embedded-hal is part of the awesomeness we want to demonstrate, and that not only comes from all the awesome crates, but also from the average ones that do boring foot work. (Not every sensor crate will have a blog post or even documentation exceeding "here's the class, and these are the constructors", especially if sensor abstractions take off and then there's really nothing to document than "this struct is for that device, pass in its I2C contact point and it provides the general accelerometer traits").

For these crates, it would be nice (maybe even awesome) to have lists of "who implements traits of that crate" or "who uses traits of that crate" easily accessible. This won't be part of a-e-r, but I don't know what it will be part of yet, but I know I eventually want entries like this:

• embedded-graphics: 2D drawing library for any size display. Implementers, users.

---

Now how do we get there? (And this is where it starts to become a bit of a scatchpad, which I hope is OK because the top half should illustrate why it belongs here too).

Starting points are:

• We currently have this manually for one crate with the embedded-hal-impl & co keywords. (People forget that, and it doesn't scale).
• crates.io has dependencies, which is a good starting point -- to implement and use a crate's traits you have to depend on it (at least indirectly, if the direct dependency pub uses something).
• rustdoc has the data as it lists implementations of a crate. It doesn't list implementers across crates in the HTML version, but it lists what is implemented for a struct, and having the information in one direction is enough (the rest is indexing / database management).

I've peeked into the output of rustdoc [lot of args from strace -f -eexecve cargo doc] -Z unstable-options --output-format json --document-private-items --document-hidden-items (private and hidden items because my test crate is embedded-nal-minimal-coaptcpserver which implements coap-message, but doesn't have a public type that does so and only passes around the implementation through as an impl MinimalWritableMessage).

Gold for the "X implements Y" side was found in an item ["index"]["0:14"], which has ["kind"] = "impl" and an ["inner"] that is has the ["for"]["inner"]["id"] = "0:4" of an item of this crate (the non-public Message) and a ["trait"]["inner"]["id"] = "20:22" of the MinimalWritableMessage trait it implements.

(The other side will be a bit harder, as "uses any implementation of" can occur in lots of places, but maybe some XPath magic can help.)

The data I think makes sense to extract is in a first stage is only on the crate level:

• "minimal_coaptcpserver implements some trait of coap-message"
• "minimal_coaptcpserver uses (by accepting any implementation of) some trait of coap-handler"

The information is available in more detail, and could gradually be expanded to which trait is shared, and (ultimately) which item of minimal_coaptcpserver implements which trait and which item ("in which position" would be taking it too far) uses which trait. That ultimate stage is IMO best left to rustdoc only.

So, the data is there, and an extractor Can't Be That Hard^TM to write. But for where?

• Can rustdoc be enhanced to the point where docs.rs makes this accessible?

  This would be nice but a bit backwards, as the first step would be the "ultimate" extension step of above across crates. (The "Implementors" section is currently largely empty if all implementations are in different crates -- see https://docs.rs/embedded-hal/0.2.6/embedded_hal/digital/v2/trait.InputPin.html#implementors for an example).

• Can docs.rs provide it?

  They already provide the dependency graph, but barely look into the crates, so if they'd provide it as part of their API, I guess that data would need to come from somewhere.

• If neither, what can host it?

  And how is it updated, especially in light of conflicting versions? (What breaks while everyone is still providing embedded-hal 0.2 but 1.0 is released?).

  For the time being, this wouldn't need to run across all crates; picking the pivot crates (embedded-hal etc) and regularly getting a list of their reverse dependencies should do for our purposes. Still, this needs to run somewhere. (Hosting as in output files is easy then, for it's just a static list of links).