Documenting is such an annoying task that should be paid double. At least. Same as fixing bugs. I haven't met anyone who likes either documenting or fixing bugs, and that's probably because if you want to do it right you have to be very careful or go through every single possibility like default parameters, etc. when all you want to do is start coding the next big feature of your application.
But because I don't have anyone to help me out with
HippoHX (snif, snif) I have to do everything myself. And as I don't want to release the GUI without documentation, I've spent last couple of days going through the APIs and adding comments all over and I'm not near finished.
I didn't want to complicate things so I've gone for the simplest:
ASDoc that comes very handy with Flex 3 SDK. And what's even handier is the integration with
FlashDevelop (beta 9). Just go to Tools > Flash tools > Documentation generator and fill in the blanks. Nice.
There seems to be a little bug though in ASDoc documentation (ain't that funny?) regarding
excluding classes. It turns out that if you want to exclude more than one class, you have to do it like this:
[code lang="actionscript"]-exclude-classes myClassOne -exclude-classes myClassTwo[/code]
Instead of this as suggested:
[code lang="actionscript"]-exclude-classes "myClassOne myClassTwo"[/code]
What I don't like that much about ASDoc is that the output looks A LOT like Adobe, because that's the tool they've used to generate
AS3 docs. You can modify the output by modifying the template that comes in asdoc/template BUT it's not a simple task. I have to review my rusty XSL skills and see how far I can go.
Cheers!
ps: There are
some discussions going on about the future of FlashDevelop, go and check it out if you use it. I think I'll post soon about Open Source projects and funding.