Popular blog posts

Recent forum posts

Discussion Forum

Documentation!

Documentation is something I have a particular fondness for. I actually got my start in the software industry as a technical writer, so I appreciate it when things are well-documented. Of course now that I am a developer I find writing documentation to be a chore!

The way I've done documentation in Rockets is to automatically generate it from the comments in the core file that contains all of Rockets' functions. However in order for this to work I had to go back and clean up and standardize all the comments, something that I had been putting off. Oh well, sometimes chores need to be done!

One thing I always disliked about most programming documentation is the requirement to understand and translate some weird meta-language or syntax for the usage of each statement. Usually it was easier to just look at the example and figure out what the author meant. So for Rockets, all my usage statements are in fact examples, albeit using names and strings that describe their actual function. So for example (open-database "database name") is both the usage and the example of opening a database.

Rocket Man on 2012-10-24 02:14:05.000

Note: For functions where there might need to be additional descriptions, especially to explain edge cases, this will be noted by a "Note:" below the usage line. In some cases I actually will provide examples as well.

Views: 5553