Sunday, March 04, 2007

Long time, no post...but progress...

Sorry for the lack of posts, but I've been busy with school and what not. Anyway, I do have some good news: I think have a tool to create source code documentation. Yes, I know there are others, however I think most are based on Javadoc which I never liked. Granted, I think this is more because people don't know how to document their code.

Anyway, the big difference between what I produced and similar tools I've seen is that what I created exports to LaTeX instead of HTML. The nice part about this is that the documentation can then be exported to several different formats. For example, converting it to HTML allows you to publish it on the web while converting it to PDF makes it easily printable.

I came up with this after learning LaTeX at work to document an API that I am working on at work. It was fantastic to be able to create good documentation that others could use without having to switch programs to create it. With gVim, I split the window vertically and as I finished parts of the API, I documented it. Unfortunately it's a manual process, so I decided to take advantage of LaTeX while automating the process.

The syntax is a bit different from Javadoc. First, I denote blocks of text to be processed with triple brackets. This was done so that only text within these blocks would be processed and nothing else. This can be useful if sections of code are commented out and you don't want them documented or you may have embedded text that's similar to the syntax I used for the documentation options. As for the documentation options, I based them off the LaTeX syntax. This made sense to me because I can define one or more elements for each option. For example, a function description has one element: the description. On the other hand, for function parameters, you could want the name, type, and description of the parameter.

To conclude, I'll probably start using it myself, but if I get a chance, I may put in on so that others can use it.


Post a Comment

Links to this post:

Create a Link

<< Home