Ben Nadel
On User Experience (UX) Design, JavaScript, ColdFusion, Node.js, Life, and Love.
Ben Nadel at CFinNC 2009 (Raleigh, North Carolina) with: Sarah Kelly
Ben Nadel at CFinNC 2009 (Raleigh, North Carolina) with: Sarah Kelly@cf_sarahk )

ColdFusion 9 Script-Based Method Definitions Work Inside CFScript

By Ben Nadel on
Tags: ColdFusion

I know this might seem like a no-brainer but, I was not 100% sure if ColdFusion 9's new script-based implementation of functions would work the same inside CFScript as they do inside of a completely script-based Component. I had no reason to think that this wouldn't work, but I just wanted to see it for myself. To test, I created a ColdFusion component, Greeting.cfc, using the standard CFComponent tags; then, I defined a method within it, sayHello(), using CFScript:

  • <cfcomponent
  • output="false"
  • hint="I am a testing component - hello world style.">
  • <cfscript>
  • /**
  • * @access public
  • * @returnType string
  • * @output false
  • * @hint I say hello to the given name.
  • **/
  • function sayHello(
  • required string name = "my man"
  • ){
  • return( "Hello" );
  • }
  • </cfscript>
  • </cfcomponent>

While the Component itself uses the CFComponent tags, the method uses the new script-based definitions, complete with JavaDoc-style attributes. I then created an instance of this CFC and invoked the given method:

  • <!--- Create a new greeting instance. --->
  • <cfset greeting = new Greeting() />
  • <!--- Output method call. --->
  • Greeting: #greeting.sayHello( "Sarah" )#
  • <br />
  • <br />
  • <!--- Output meta data. --->
  • <cfdump
  • var="#getMetaData( greeting ).functions#"
  • label="Function meta data."
  • />

When I ran the above code, I got the following output:

ColdFusion 9's CFScript Updates Work Inside Of A Tag-Based Context (CFComponent). 

As you can see, not only did the method work as expected, but the MetaData of the component functions reveals to us that the JavaDoc-style attributes were implemented properly.

Again, I had no real reason to think that this wouldn't work; but, since the CFScript side of the language is starting to get *almost* as beefy as the Tag-based side, I just wanted to make sure they would play nicely together.

Reader Comments

As much as I am in love with CFSCRIPT, using JavaDoc for defining function attributes gives me the willies! Just doesn't seem right. The whole "Doc" part of "JavaDoc" feels violated. :)

Adam - Just to be clear you *don't* need to use the javadoc syntax. You can define component, parameter and function level attributes using both inline and javadoc syntax.

@Dan, oh yes, I use the actual function syntax. I raise a concern of showing the JavaDoc syntax for defining a function only cause I feel its use is tenuous. If you accidentally mistype something in the JavaDoc syntax, does CF throw an exception, or happily ignore it?

Admitting that I know little about JavaDoc, but does it carry through to documenting the component when the component is called from URL?

Typically, I don't like the Javadoc style notation. For things like like the Component and the Property tag, I use inline attributes.

My problem with the Function is that it has inline attributes both BEFORE and AFTER the method signature... which is kind of junky.

I love the JSDoc syntax personally. In JavaScript, using /*! styled comment for the file description and the /** styled comment for the class and method descriptions feels right after a while, Aptana's editor bolds the @attributes and it is really readable an super easy to edit, I hated the thought of not using FuseDoc style any more but now I love JSDoc/JavaDoc/CFScriptDoc format :)

The biggest problems are not being able to use the data type requirement with dots and that the @attributes are not stored very well, the output just doesn't look right when you dump a getMetaData to me since I like to include the data types as part of the comment block, I have found one way around it. I use:
@param {MachII.framework.Event}event I am the Mach II Event object.

That gives an attribute of "@param {MachII.framework.Event}event" which equals "I am the Mach II Event object." that I can process and split up if needed. With any luck I can figure out a way to colour code the @attributes and {dataTypes} like Aptana JSDocs do and then I will be even happier :)

no it doesn't all carry through to the documentation system from what I have found, I guess there's more for Adobe to do on it still, hopefully it will work better in CF10.


That's cool to know that Aptana knows how to intelligently use the JavaDoc style comments. That's what a good IDE is all about.

I am not sure what you mean about the Dump output of the objects with comment-style meta data? The CFDump in my blog post looks good?

I just meant when you want to have pathed objects like MachII.framework.Event, you can't currently so using the param syntax found in JSDocs is just a quick way to document your function and have all the information there.

The not looking right part was in relation to attributes you store not the parameters, in the documentation I found the example of:
*@hint "this is a hint for component"
Doing so produces a dump containing both:
hint="this is a hint for component"
hint "this=is a hint for component"

But using quotes in other attributes gets messier and only gives the second mistaken variant if it isn't a predefined CF attribute, so I think that's a documentation error about documentation :)

The Aptana JSDocs prefix any new line with the appropriate whitespace and asterisk, so unlike in CFBuilder you don't need to hit enter > asterisk > space before you want to type on the next line, it is great, I hope Adobe fix it for the next beta. And I hope that comes soon I love doing JSDoc styled documentation done right! :)


Oh that is bizarre. I quickly learned that using quotes was not going to work. The double-dump you are getting is very strange. I see what you're talking about now.