4 ms·
In rustdoc, documentation examples are compiled and run whenever you run your tests. It's very helpful for this kind of thing. https://doc.rust-lang.org/stable
by steveklabnik 9y ago
In rustdoc, documentation examples are compiled and run whenever you run your tests. It's very helpful for this kind of thing.
https://doc.rust-lang.org/stable/rustdoc/documentation-tests.html https://doc.rust-lang.org/stable/rustdoc/documentation-tests...
- vog 9y agoNice! Python has doctests which serve a similar purpose: https://docs.python.org/3.6/library/doctest.html https://docs.python.org/3.6/library/doctest.html
- slimsag 9y agoJust wanted to chime in and say that as a Go developer of almost 5 years now, running into Rusts' compiled examples has been quite cool. The cool thing about these is that you can actually (depending on the situation) make your examples your tests.
- slrz 9y agoWhat makes them so different from godoc's examples?
- tareqak 9y agoThanks for the example! To be completely clear, this is what I meant: Suppose this is the function we want to document (using examples modified documentation tests: fn foo { let x = 5; let y = 6; println!("{}", x + y); } Suppose we have a documentation requirement/heuristic of requiring the comment to have all the variables that are declared in the body of any given function. Then a comment like this would pass because whatever compilation step /processor sees that `x` and `y` both appear in the comment. // Prints x + y This would fail because `x` is not found: // Prints z + y This would pass but is not useful/misleading/wrong. // y - x FTW!!! This example is trivial and only uses the one simple heuristic such that it is both onerous and useless, but it would force the writer of the code to also write comments in accordance with said heuristic. In this particular case, if someone modifies the variable name, adds a new variable, or removes and existing once, then the compiler would force that individual to make a necessary change to that particular comment such that the comment cannot become stale (but the heuristic is bad, so it could still be useless :) ).
- hamandcheese 9y agoI would argue that externally documenting declarations inside the function is not particularly helpful.
- twic 9y agoPython has something similar: https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html For software with a command-line interface, perhaps it would be useful to do some testing at that interface, perhaps using BATS: https://github.com/sstephenson/bats https://github.com/sstephenson/bats That is also automatically tested, but describes the actual user interface.