From a1eeaa61fd48a64ffb83826c28128702c8b173c9 Mon Sep 17 00:00:00 2001 From: Will Crichton Date: Fri, 3 Sep 2021 19:40:31 -0700 Subject: [PATCH] Simplify image markdown, add alt text --- text/3123-rustdoc-scrape-examples.md | 22 +++++----------------- 1 file changed, 5 insertions(+), 17 deletions(-) diff --git a/text/3123-rustdoc-scrape-examples.md b/text/3123-rustdoc-scrape-examples.md index 38c330e29c5..f14e5b11fee 100644 --- a/text/3123-rustdoc-scrape-examples.md +++ b/text/3123-rustdoc-scrape-examples.md @@ -17,19 +17,12 @@ Code examples are an important tool for programmers to understand how a library As a parable of the value of examples, I recently did a small user study where I observed two Rust programmers learning to use the [warp](https://github.com/seanmonstar/warp) library for a basic task. Warp is designed around a generic [`Filter`](https://docs.rs/warp/0.3.1/warp/trait.Filter.html) abstraction. Both participants found the documentation for `Filter` methods to be both imposing and too generic to be useful. For instance, [`Filter::and`](https://docs.rs/warp/0.3.1/warp/trait.Filter.html#method.and): - -Screen Shot 2021-05-09 at 7 49 35 PM - -

+Rustdoc documentation for Filter::and in the warp crate The repo authors also included a code example. But neither participant could understand the example because it lacked context. - -Screen Shot 2021-05-09 at 7 56 03 PM - -

- +Example code for Filter::and The participant who was less familiar with Rust struggled to read the documentation and failed to accomplish the task. By contrast, the participant who was more familiar with Rust knew to look in the `examples/` directory, where they found a wealth of examples for each function that complemented the documentation. For instance, [`rejection.rs`](https://github.com/seanmonstar/warp/blob/bf8bfc4134035dbff882f9b26cb9d1aa57f2c338/examples/rejections.rs) shows the usage of `and` in combination with `map`: @@ -54,19 +47,14 @@ The goal of this RFC is to bridge the gap between automatically generated docume The `scrape-examples` feature of Rustdoc finds examples of code where a particular function is called. For example, if we are documenting [`Filter::and`](https://willcrichton.net/example-analyzer/warp/trait.Filter.html#method.and), and a file [`examples/returning.rs`](https://github.com/seanmonstar/warp/tree/bf8bfc4134035dbff882f9b26cb9d1aa57f2c338/examples/returning.rs) contains a call to `and`, then the corresponding Rustdoc documentation looks like this: - -Screen Shot 2021-05-11 at 11 31 12 AM - -

+ +UI for scraped examples shown with Filter::and After the user-provided documentation in the doc-comment, `scrape-examples` inserts a code example (if one exists). The code example shows a window into the source file with the function call highlighted in yellow. The icons in the top-right of the code viewer allow the user to expand the code sample to the full file, or to navigate through other calls in the same file. The link above the example goes to the full listing in Rustdoc's generated `src/` directory, similar to other `[src]` links. Additionally, the user can click "More examples" to see every example from the `examples/` directory, like this: - - Screen Shot 2021-05-11 at 11 31 36 AM - -

+Additional examples are shown indented under the main example To use the `scrape-examples` feature, simply add the `--scrape-examples` flag like so: