This is Week 2 of my Google Summer of Code project. In this week, I will talk about why documentation is important and show you a simple bear that capitalizes every uncapitalized sentence. (I know!, right?)
When we talk about documentation in a codebase, we generally mean documentation of objects, i.e. of classes and functions. This helps future hackers to get started easily with the codebase. The general convention is to give a brief explanation of the object, describe the parameters it takes and what it returns. Does this work?
Generally, yes. Most projects do this, and it should work. But the right question to ask, “Is it for humans?”
This is why hand-written documentation is important. I personally think a right-mix of generated API documentation and hand crafted documentation works well. This is what we do at coala!
The bear I wanted to talk about doesn’t do much right now, but the key takeaway was that I was able to successfully parse the documentation, analyze and manipulate each section, and assemble back the documentation. I have recorded a small asciinema to demonstrate this: