Will Crichton

You can enable this feature on nightly via: cargo +nightly doc -Z unstable-options -Z rustdoc-scrape-examples=examples And on http://docs.rs  via: [http://package.metadata.docs.rs ] cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples=examples"]

As -Zunstable-options implies, this feature is unstable. I am actively looking for feedback and bug reports. Any suggestions for the UI are welcome!

Some interesting questions: * How should examples be ranked? (Now: by size.) * How should examples be displayed? (Now: show 1, show 5 more under a button, then link to the rest.) * How should this feature be configured? Eg should we allow items to be annotated with `no-scrape`?

This feature also showcases human-centered language design. This concept was based on a formative study of barriers to learning Rust APIs. It was clear that novices were struggling in part because they didn't know where to find examples, or that they existed.

(After the PLDI deadline, I will get around to describing the design process in greater detail.)

This feature also shows the challenges of taking an HCI concept from prototype to production. 90% of the work was the logistics of integrating with Rustdoc, Cargo and http://Docs.rs . If I had just published a user study, very unlikely the concept would have been built.

Example: scraping examples requires analyzing code *that depends on a library* before *documenting that library*. This inversion of the usual dependency order did not play well with Cargo.

But a key factor in getting this built was all the help and encouragement I received from the Rustdoc devs and others in the Rust community. Very grateful to them for their (unpaid) time spent discussing the RFC, answering questions, and reviewing my code!