Despite our best efforts, the Daemonites still struggle at keeping documentation up to date. Documenting tags and functions is tortuous. Maintaining that documentation on an evolving code base is even worse. Might as well attempt to turn back the tide, or change global temperature by eating tofu.
Encourage developers to document and code simultaneously. Adopt a commenting standard and apply some discipline when you update code; you just might get closer to automated documentation Nirvana.
We've started applying this strategy to ColdFusion components and custom tags. But rather than beating developers with a stick, we've dangled a carrot by building CFEclipse code hinting dictionaries that help developers day to day.
The theory: keep code hints up to date, code faster in Eclipse. The side effect: documentation.
The CFEclipse Dictionary Generator is ColdFusion utility that parses directories of components and tags, and generates an XML dictionary that can be used with your CFEclipse projects. We've been using it in the FarCry Community for a while. Thought it was time we made it available to more ColdFusion developers.
Update your code with relevant comments. Download the code, and drop into any ColdFusion web root. Select the location of the code libraries you want to process, and generate the dictionary. Then update your Eclipse installation to use the dictionary.
We're just "stealing underpants" at this stage. But heh if you use Eclipse for ColdFusion development I'm sure you'll find the CFEclipse Dictionary Generator a lot of fun. Next step, take the same metadata and build dynamic, printable documentation. Then profit...