4 ms·
Just to bring up a neat point, this doesn't guarantee that the documentation and the code are the same, as you could change code without updating documentation.
by lytedev 7y ago
Just to bring up a neat point, this doesn't guarantee that the documentation and the code are the same, as you could change code without updating documentation.
A very slick way of enforcing this that I've seen is having actual unit tests in your documentation (and of course a CI tool to enforce that tests pass). This is something that I think is extremely cool about Elixir! It forces you to think about testing, documentation (with ACTUAL examples!!), and the problem you're solving all at once. It's a very neat concept.
https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-with.html#doctests https://elixir-lang.org/getting-started/mix-otp/docs-tests-a...
- j88439h84 7y agoAFAIK Doctest actually comes from Python originally.
- sambal 7y agoPython and Rust go the “documentation test” route as well. Go goes the opposite direction with “testable examples” that are written alongside test code and added to generated documentation. https://docs.python.org/2/library/doctest.html https://docs.python.org/2/library/doctest.html https://doc.rust-lang.org/rustdoc/documentation-tests.html https://doc.rust-lang.org/rustdoc/documentation-tests.html https://golang.org/pkg/testing/#hdr-Examples https://golang.org/pkg/testing/#hdr-Examples