by Chris Zheng, on clojure, testing, documentation, midje-doc
I hope that this topic will get a little bit more attention if I post on my blog instead of Google Groups.
Question: Why do we still write our github
readme.md if we can generate a whole bunch of human readable docs using javadoc, codox, marginalia or any other doc-string generation library?
Answer: Because the output documentation is not as human readable as we'd like them to be.
Documentation generated from those libraries are great as references, but only after we have familiarized ourselves with the readme. However, there are still two more basic problems with this approach:
- doc-strings are not as good as tests at describing what a function does.
- we have no idea that examples given in doc-strings and readmes are correct.
I wrote midje-doc because I was fed up with writing documentation that became incorrect with code updates. I exploited the way tests are defined in midje to add additional markup to test code so that a complete readme could be generated from test files.
The project has been hacked together but it has changed the way I write tests and documentation. These two previously seperate stages of coding have now come together, allowing a much higher-level of thought and design in the coding process. It also allows me to write a readme file that is beautiful, correct and up-to-date.
Eating my own dog food:
Below are documentation for my current libraries, all generated from my test files. They are very readable and I have 100% confidence that every example in the document is correct for that version of the library:
Here is a video
demonstration of my test/documentation workflow. For those that wish to cut to the chase, skip to the 7:20 mark
I hope that this post can show that documentation doesn't have to be painful if we have the right tools to do so. I also wish to create a bit more awareness of using this integrated approach of documention/test/design, mainly for selfish reasons: I am currently quite time poor and so I hope that someone smarter than me can help pick up this project and run with it.
There is a huge wish-list of features on the project page that I want, not to mention what others will come up with. Please ping me if you are interested =)