25 May 2009, Posted by Matthew Reinbold in PowWow,Tools, 1 Comments

Natural Docs, Auto-documentaion from Source Code: Vox Pop Pow Wow 2009-05-18

Working in small, distributed teams can be an exercise in loneliness. The solitary existence can mean missing out on a shared revelation or not getting feedback on a forming assumption. The Vox Pop Pow Wows are a chance for a group of peers to get together over Skype, talk about the news of the day, and provide that professional support that we otherwise might go without. Here’s the transcript from a recent talk [edited for readability].

A. – Matthew Reinbold, Founder and Creative Principal, Vox Pop Design
B. – Matthew Orstad, Founder and Chief Engineer, Rocket Midwest

Natural Docs, Autodocumentaion from Source Code

A. I wanna spend a little time talking about Natural Docs. It’s a effort that spans a number of different languages including php and Java and, in our case, ColdFusion. It’s a natural way of writing documentation in code. When you’re all done you click a button and it generates either pdf or html based rich documentation based on your project. I’ve been increasingly been looking for something like this because I need some form of formal documentation with certain projects. Having the headers of the various CFC’s is not enough. I certainly don’t want to have to have two different unrelated files: a code file and a documentation file and have the situation where I do a bunch of updates and then I forget to update the documentation and vice versa. That’s one reasons why I don’t’ think having all of the documentation on the wiki, like in Trac, works. Most of it needs to be driven by the code itself so as you’re changing and modifying the source the documentation is going to be updated automatically.

It looks fairly straightforward. I haven’t played with it but I want to. And, it may be something that going forward this becomes kind of like a Vox Pop standard; that when you do your code if you have any documentation you need to write it in the syntax so that it gets sucked up into the documentation in the expected way.

B. Neat.

A. I’ve also been looking into Ant for streamlining some of the roll-out processes. This certainly seems like something that would be very easy to incorporate into an Ant script. For example, you get done with a piece of code and, before you check it in, it goes through a batch of Selenium tests and makes sure that everything is okay. It runs some unit testing and then – if all that completes successfully – ANT generates documentation, ftp’s the code to the appropriate server, and finally pops some champagne cause you’re done. Something like that. Something modest.

B. I’m really kind of interested in this. I have been a little unimpressed with the documentation generation for languages other than Java, unfortunately.

A. Right.

B. But I haven’t seen this one and it looks like it’s got some momentum.

A. It has such broad support (C++, C#, Java, Pearl, Php, Python, Visual Basic, Action Script, Pascale, java script, Ruby, TLC, Cold Fusion). I’m wondering if it’s not on it’s path to becoming a standard. If you learn it in one language, like ColdFusion, then that’s not information or knowledge that you need to throw away if you happen to be doing a PHP project. You learn it once and use it across a broad base of different languages. That’s not a bad thing.