Ask the Crowd: Documentation

Brian asked:

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.

Raymond Camden's Picture

About Raymond Camden

Raymond is a developer advocate. He focuses on JavaScript, serverless and enterprise cat demos. If you like this article, please consider visiting my Amazon Wishlist or donating via PayPal to show your support.

Lafayette, LA https://www.raymondcamden.com

Comments