generate tests from code example docstrings (to fight bitrot) #2925
Comments
|
Yes, this seems like an obviously good idea to me. I think it is an RFC-level change, though, since it would result in rejecting more programs (which is a good thing!), so I'm adding the RFC label. |
|
The easiest way is probably to use rustdoc to convert the documentation to markdown, then run the python script over it to generate tests. Here's my preference:
Later, once we've created a unified |
|
So, this issue is a request for infrastructure for generating execution unit tests from the embedded documentation for a symbol. That sounds like a match for Maturity Milestone 4: well covered. |
ghost
assigned 
|
Absorbing under rustdoc2 |
|
Tests can be extracted from the doc comments present in the JSON rustdoc_ng emits. Tooling needs to be made to do so, and to build+run the tests. |
|
part of #8125 |
|
Unassigning self. |
|
Nominating, this is the only way we're going to have code examples be reliable |
Changes: Remove now-useless `allow(unknown_lints)` Stabilize tool lints Use `impl Iterator` in arg position in clippy_dev Fix fn_to_numeric_cast_with_truncation suppression Limit commutative assign op lint to primitive types Clarify code Fix rust-lang#2937 Fix cast_possible_wrap and cast_sign_loss warnings Fix cast_possible_truncation warnings Fixes rust-lang#2925 cmp_owned false positive if_let_redundant_pattern_matching: use Span.to() instead of Span.with_hi() to fix crash. Improve diagnostics in case of lifetime elision (closes rust-lang#3284) Fix items_after_statements for `const`s Fix items_after_statements for sub-functions Fix items_after_statements for `use` statements Don't suggest cloned() for map Box deref Fix excessive_precision false positive Fix FP in `fn_to_numeric_cast_with_truncation` new_without_default should not warn about unsafe new fix command to manually test an example Add license to README Adding more detail to filter_map lint documentation. additional people Add license header to other files Add license header to Rust files Relicense clippy Document relicensing process Fix util/export.py to include lints from methods
Changes: Remove now-useless `allow(unknown_lints)` Stabilize tool lints Use `impl Iterator` in arg position in clippy_dev Fix fn_to_numeric_cast_with_truncation suppression Limit commutative assign op lint to primitive types Clarify code Fix rust-lang#2937 Fix cast_possible_wrap and cast_sign_loss warnings Fix cast_possible_truncation warnings Fixes rust-lang#2925 cmp_owned false positive if_let_redundant_pattern_matching: use Span.to() instead of Span.with_hi() to fix crash. Improve diagnostics in case of lifetime elision (closes rust-lang#3284) Fix items_after_statements for `const`s Fix items_after_statements for sub-functions Fix items_after_statements for `use` statements Don't suggest cloned() for map Box deref Fix excessive_precision false positive Fix FP in `fn_to_numeric_cast_with_truncation` new_without_default should not warn about unsafe new fix command to manually test an example Add license to README Adding more detail to filter_map lint documentation. additional people Add license header to other files Add license header to Rust files Relicense clippy Document relicensing process Fix util/export.py to include lints from methods
This check is redundant in our CI since the bookrunner job already builds the documentation. It is also often breaking the regression job. Co-authored-by: Jaisurya Nanduri <91620234+jaisnan@users.noreply.github.com>
So I'm going through my contributions and adding code examples for most of the API stuff out there that isn't immediately obvious.
I only have one example of an existing code sample that is live in the libstd docs right now, and that's for
net::tcp::listen. Suffice to say: it is very out-of-date with the current state of the art for rust. This is a sad discovery, on my part.Since more literate code examples in the docs is probably a good thing, this is where I'm putting my energies for documentation of my work (as opposed to blog posts, emails to the list, etc). I'm trying to make the examples complete, illustrative and durable (the latter of which I have no control over).
Cutting to the chase:
I'd be happy with something like what (I'm told) we have in the tutorial markdown: have the build automation (rustdoc, in this case?) do a run-pass on all code blocks (by some known convention) that appear in docstrings, for the greater good.
Thoughts?
The text was updated successfully, but these errors were encountered: