CFEclipse Dictionary Generator Released
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...
Comments
rob on 14 Sep 2008 07:58 AM
Awesome! I can't wait to check it out
Daniel Short on 15 Sep 2008 02:09 AM
Do you have an example of how the comments should be placed? From the documentation it's not clear how I would use this. It sounds awesome, but the implementation details are unclear for me...
Geoff Bowers on 15 Sep 2008 08:29 AM
For examples of comments try: http://docs.farcrycms.org/display/FCCORE/Auto-Documentation I'll take a look at updating the documentation to include these sorts of examples.
AJ Mercer on 15 Sep 2008 03:45 PM
This is like totally awesome. Thanks for sharing
Jim Priest on 16 Sep 2008 09:06 PM
Very cool!!! Thanks for sharing this!
jan on 17 Sep 2008 11:47 PM
This is really cool. Thanks for sharing! I added a little recursion to the scrapeComponent function in the scrape.cfc and now inheritance (cfc extends) is also supported. Maybe you can include/enhance this: <cffunction name="scrapeComponent" access="public" returntype="struct" description="Returns a struct containing metadata for a component"> <cfargument name="stMetadata" type="struct" required="true" hint="Component metadata" /> <cfset var stResult = structnew() /> <cfset var i = 0 /> <cfset var extendsMetadata = 0 /> <!--- Component package path ---> <cfset stResult.packagepath = arguments.stMetadata.fullname /> <!--- Component name ---> <cfif structkeyexists(arguments.stMetadata,"displayname")> <cfset stResult.name = arguments.stMetadata.displayname /> <cfelse> <cfset stResult.name = listlast(stResult.packagepath,".") /> </cfif> <!--- Component hint? ---> <cfif structkeyexists(arguments.stMetadata,"hint")> <cfset stResult.hint = arguments.stMetadata.hint /> <cfelse> <cfset stResult.hint = "" /> </cfif> <!--- Component preloaded location ---> <cfif structkeyexists(arguments.stMetadata,"scopelocation")> <cfset stResult.scopelocation = arguments.stMetadata.scopelocation /> <cfelse> <cfset stResult.scopelocation = "" /> </cfif> <!--- Functions ---> <cfset stResult.functions = structnew() /> <cfloop from="1" to="#arraylen(arguments.stMetadata.functions)#" index="i"> <cfif (not structkeyexists(arguments.stMetadata.functions[i],"bDocument") and structkeyexists(arguments.stMetadata.functions[i],"access") AND arguments.stMetadata.functions[i].access eq "public") or (structkeyexists(arguments.stMetadata.functions[i],"bDocument") and arguments.stMetadata.functions[i].bDocument)> <cfset stResult.functions[arguments.stMetadata.functions[i].name] = scrapeFunction(stMetadata=arguments.stMetadata.functions[i],scopelocation=stResult.scopelocation) /> </cfif> </cfloop> <!--- START: added by jan on 2008-09-17: support inheritance ---> <cfif structKeyExists(arguments.stMetadata, "extends") and structKeyExists(arguments.stMetadata.extends, "functions")> <cfset extendsMetadata = scrapeComponent(arguments.stMetadata.extends) /> <cfset structAppend(stResult.functions, extendsMetadata.functions, false) /> </cfif> <!--- END: added by jan on 2008-09-17: support inheritance ---> <cfreturn stResult /> </cffunction> jan from germany
jan on 17 Sep 2008 11:51 PM
sorry for the format!