rfcs
rfcs copied to clipboard
rust-lang
Multi-part examples in rustdoc
I personally don't think this is a needed addition: it seems to be a bit too much specific to be really useful (or used).
I'm interested to see what the others in the @rust-lang/rustdoc team think about it though.
I personally don't think this is a needed addition: it seems to be a bit too much specific to be really useful (or used).
I think this is useful, although it does stretch the scope of rustdoc a bit. I'd like to hear from library authors, since they'll be the ones using it - @darksonn @BurntSushi @dtolnay would you be interested in this?
I do sometimes write things in this style, but I have not found the need to do so in our API reference. The examples there are not really complicated enough to warrant it in my experience.
Maybe it would be more useful in mdBook?
I would love to have this for Bevy! Actually demonstrating functionality can involve quite lengthy, multipart code, and we rely heavily on our stand-alone and docs-integrated examples as integration tests.
I wonder what @carols10cents thinks of this RFC. I have not read it yet, but this feature in general feels like something that we may want to take advantage of in the book. I know at various times I've wanted something like this in long-form writing about Rust.
This is a really nice-to-have feature. I especially like the idea of adding arguments to ``` for special behaviors, which resembles RMarkdown.
I have not read it yet, but this feature in general feels like something that we may want to take advantage of in the book. I know at various times I've wanted something like this in long-form writing about Rust.
Doesn't the Book use mdBook though?
@camelid unless something has changed (or i am 1000% misremembering), mdbook calls out to rustdoc.
@camelid unless something has changed (or i am 1000% misremembering), mdbook calls out to rustdoc.
Ah, I forgot that mdBook uses rustdoc for tests 👍
So yes, the book does use mdBook, and mdBook takes Rust code blocks from the markdown files and then runs rustdoc test on them. So it's kind of backwards from library documentation.
When we have long examples in the book that we explain in pieces, I'm using the rustdoc_include feature with anchors. The code actually lives in separate files so that we can provide complete, standalone Cargo projects for each code listing (and can run rustfmt on them, save the output of running them to include in the text as well, and do other stuff that I doubt is relevant to library documentation).
I believe there are a few cases where one code file has multiple anchors in it, so that we are accomplishing the same goal that is here of having text interleaved with multiple parts of one long code example. But most of the time, in the book, we're helping the reader to build up an example from nothing, and it's not often straightforward like "add lines 3 and 4, then add lines 5, 6, and 7". Usually it's "we're going to write a function that returns a static value, ok now we're going to take an argument, ok now we're going to change the return type, and now we have to change the call sites too". So it's more applying changes to one example to build it up, rather than explaining it line-by-line.
So I don't think this feature as written would be relevant to the book, is what I'm trying to get at.
Now, for library documentation, I personally find it very difficult to write long doc comments anyway, to get them to show up where I think people would look for them in the moment they need them. And writing markdown inside /// lines isn't a great experience, writing Rust code within Markdown within doc comments even more so. If I provide an example in a doc comment, it's going to be very short and something to just give the general idea of how you'd call something as reference, not a tutorial with lots of text around it. I think mdBook or other tools are better for the tutorial kind of documentation, at this point (I'm not sure what the best tool for writing tutorials is, but I'm familiar with mdBook and it integrates with Rust code well enough, so it's what I'd currently use in this case).
So overall, I'm not sure that adding this feature to rustdoc would be useful. I do, however, appreciate the thought that has gone into this RFC and appreciate the desire to make docs better!
As a library author that writes lots of examples, I'm not sure I would have much use for something like this personally. While I'm not quite as pessimistic about writing code inside of /// comments as @carols10cents (perhaps because I've done it so much that my brain has adapted to it haha), I do not often find myself in situations where I have drawn out examples that would require something like this. In cases where I do, I often find it better to find a way to simplify the example somehow. When that's not possible, putting comments inside the code block is usually good enough for me. It's likely I would continue doing that in most cases even if this feature were present, since I think splitting up examples into multiple chunks can be a bit disorienting unless the situation really calls for it. But maybe this is a feature where if it were present, I'd find more use cases for it.
With respect to the UI mockup, I have two comments/questions:
- What does the "run" button do on each of the snippets? I would guess that the "run" button does the same thing for each snippet in an entire example: it runs the whole thing. Where does the output get displayed?
- Is there a way to copy the entire code block stitched together? Otherwise, users will have to copy each individual block if they want to copy an example into their project.
Prompted by @carols10cents' comment, I realized that I would be much more inclined to write longer form documentation1 if the effort involved with publishing a book was reduced. To that end, I'm suggesting that docs.rs build and host mdBook content. That may be a complete alternative to this RFC.
1 — And I already try to write longer form documentation inside of my more user-facing crates. For example, SNAFU has an entire guide module that is only documentation.
think this is useful, although it does stretch the scope of rustdoc a bit. I'd like to hear from library authors, since they'll be the ones using it - @Darksonn @BurntSushi @dtolnay would you be interested in this?
I've been missing this a lot: I come from Python where doctests are widely supported. Doctests in Python allow you to save state between code blocks and this is very useful to be able to show a continued worked examples. Here is a random example from Scipy where they first define a matrix and then verify some property of it in the next code block:
Note how the second code block uses a defined in the first. I hope to write similar documentation in Rust where I only need to import modules once per docstring.
