- What is it?
- What does it do?
- Why does it do that?
- What is the API?
- What does it return?
- What are some examples of proper, real world usage (that don't involve foo/bar but instead, real world inputs/outputs I'd likely see)?
- What is it?
- What does it do?
- Why does it do that?
- What is the API?
- What does it return?
- What are some examples of proper, real world usage (that don't involve foo/bar but instead, real world inputs/outputs I'd likely see)?
But then I realized that a lot of what makes a set of tests good documentation is comments, and those rot, maybe worse than dedicated documentation.
Keeping documentation up to date is a hard problem that I haven't yet seen solved in my career.
My favorite example is Stripe. They've never skimped on docs and you can tell they've made it a core competency requirement for their team.
At its core, a good test will take an example and do something with it to demonstrate an outcome.
That's exactly what how to docs do - often with the exact same examples.
Logically, they should be the same thing.
You just need a (non turing complete) language that is dual use - it generates docs and runs tests.
For example:
https://github.com/crdoconnor/strictyaml/blob/master/hitch/s...
And:
https://hitchdev.com/strictyaml/using/alpha/scalar/email-and...