I am in the documentation stage of my web application - yuck! I am curious what others use to create documentation (user, developer, etc) for their ColdFusion web applications? I know that the CFCs are self documenting, but are there any parsers that you are aware of that take care of regular CFM files? I have glimpsed at docBook, which seems to be popular in some circles. Do you know of a ColdFusion community documentation standard (tools, format, etc)?
Woot, something to talk about besides climate change. I labelled this blog entry “Ask the Crowd” as I really don’t have a great answer. I’ll explain what I do and I hope that my readers take up the challenge and share their thoughts as well. So let me address your smaller questions first. Am I aware of any CF parsers for documentation? Back in the old days I wrote support for UDFDoc. This was a script that would parse comments in CF UDFs and generate HTML docs. All UDFs at CFLib still use this comment syntax which is based on JavaDoc.
As for other examples, I went to RIAForge (which has been up for days thank you very much - how come everyone emails me when it’s down but no one cares when it works?? ;) and searched for ‘doc’ in the ColdFusion category. This returned the following results that I thought were relevant:
CFCDoc revamped - Create JavaDoc like documentation for your CFC’s
CFTagDoc - Similar to CFCDoc, a documentation tool for CF Custom Tags
ColdDoc - Port of Javadoc for CFCs, that generates static HTML files for API documentation
ezDoc - ColdFusion CFC Documentor
I’ll also point out cfcToPrinter - a UDF at CFLib that will take the autogenerated CFC documentation and create a nice HTML/PDF/FlashPaper version.
So I think you were mainly looking at automatic documentation generation, but I think we can, and should, open this discussion to manual solutions as well. Personally I tend to use OpenOffice to generate a Word document. I export into PDF and ship both Word and PDF versions as I figure that should cover everyone in the universe. I’m a big believer in good docs, although I honestly don’t always follow my own advice. I’ve tried to ship good sets of docs for my larger open source applications, but for some of the smaller ones I let the CFC be the doc.