Have you ever read a book and walked away inspired? I found myself reading The Pragmatic Programmer at a friend’s reccomendation. A book full of interesting ideas and advice. In particular, a suggestion of programatically generating documentation struck me as a thing I would find useful. Because let’s admit it, sometimes we forget things about functions, objects, etc. I shall call it, Autodex! Because things need names.
The core components of this would be as follows:
- Parse source code for names of classes, functions and variables.
- Build explanations of said classes functions and variables.
- Find and list TODO’s.
- Build the documentation as .html files.
Different languages are written and structured differently. Do they need to be defined individually, or can they worked out algorithmically? In the former case, an XML “dictionary” might be sufficient to add support for a language.
Picking Up on Comments
The item descriptions have to come from somewhere. Personally I tend to briefly explain a function I write in comments (unless the name makes it obvious), so we should be able find the comments in the vacinity of an item and apply some simple logic to figure out whether that comment applies to this item.
What Language to Use
While I imagine python to be the better option (I’ve used it to parse files more than Java) Java is more widely used, meaning I might be able to get away with not having python on a machine, while I will inevitably always need Java on all of my machines.
Building/Structuring the HTML
Why HTML and not something dynamic? Because dynamic sites need to be run by some kind of server application. The problem arrises when it comes to laying out these pages, because I can do content but can’t design for squat.
What I should end up with is a command-line application that parses source code and builds a list of classes, functions and maybe variables. It will most likely use xml files as dictionaries depending on file extensions.