Creating Multiline Descriptions With JavaDocs And CFScript In ColdFusion
Super minor post here, but the other day, I stumbled across a nice behavior in the JavaDocs syntax for ColdFusion components and methods. When I first learned about the JavaDocs syntax, I missed this; but, apparently, all of the content in the comment that is defined before the first "@" parameter will automatically get added as the @hint attribute. This means that you can easily create multiline descriptions for your ColdFusion components and functions by leading with the hint content, rather than trying to define your own explicit @hint attribute.
To see what I mean, take a look at this simple example - notice that the first part of the JavaDocs comment contains multiple lines of text:
/**
* I am a Thing - I provide access to thing related stuff so that you can do things
* with things that are really cool. But, of course you probably already knew that,
* which is why you are working with this Thing to begin with.
*
* @output false
*/
component {
/**
* I return an initialized thing. This method doesn't take any arguments, but
* don't let that fool you - this method does a lot of stuff. It has all kinds
* of awesomey goodness baked right into the logic - you just can tell from
* the outside.
*
* @output false
*/
public any function init() {
return( this );
}
}
When we dump out the meta-data for this ColdFusion component, we get:
Notice that the multiline content at the start of each JavaDocs comment became the Hint attribute of the ColdFusion component and function meta-data.
The hint attribute has zero effect on the actual functionality of the ColdFusion component or method. But, if you know me, you know I love comments; and this will change the way that I'll be defining my comments in the future. I never really embraced the JavaDocs syntax before; but this really puts me over the edge and allows me to define comments in a format that feels good and is functional.
Want to use code from this post? Check out the license.
Reader Comments
Actually, the comments *do* impact the behavior - not the @output false. This is the only thing I *really* don't like about this feature. IMO, comments should *never* change the behavior of code.
That is quite nice. I'm assuming arguments with hints shows the hints as well? I wonder if you
Comments (in code) is like a cold, vanilla icecream on top of a warm, rich, stacked brownies, on a day like today - they make the brownies taste and look good ;)
I know, I know... that's a stretch - I like comments, relevant comments, that is. This isn't so.
@Ray,
Yeah, it's definitely an odd thing. The only part that I would really put in the JavaDocs for behavior stuff is the output=false stuff since the syntax for putting that in the function definition is really odd looking:
public void function foo( ... args ... ) output = false { .... }
That's just crazy sauce.
@Jojo,
To be honest, I had to double-check this because I couldn't remember. It looks like if you define an "@" that matches the argument name, it will define the hint:
/**
* @id This is the description of the ID argument.
*/
function Foo( required numeric id ) { ... }
If you dump out that meta data, the content following the @id will show up as the Hint for the ID argument.
@Ben / @Ray -
That's cool. I tried looking at the cfcexplorer just to compare, y'all are right - it is an odd thing that the comments affect the behavior of the component and it throws an error if property is defined in both the comments and the attribute.
/**
* Component test
*
* @persistent = false
*/
component
persistent = false,
hint = 'I override the /component test/ hint above' {
}
Returns:
Attribute validation error.
A duplicate attribute PERSISTENT has been encountered. Attributes with the same name cannot be provided more than once.
That's not cool.
@Jojo,
Hmm, I think that error is a bug. It's my understanding that the tag-based settings should *override* the same settings set in the comments. In fact, here is an example from the Adobe Docs:
http://help.adobe.com/en_US/ColdFusion/9.0/Developing/WSE99A664D-44E3-44d1-92A0-5FDF8D82B55C.html
/**
* @hint "This function displays its name and parameter."
*/
public void function foo(String n1=10)
description="does nothing" hint="overrides hint" (
....
}
Note that the inline hint states, "overrides hint". So, either:
1. The docs are buggy.
2. The override feature only applies to certain types of attributes - which could make sense.
3. The error you got is a bug.
Not sure which it is... though, in general, you should probably have one source of truth for the features and not try to override.
@Ben -
'hmmm' it is. I failed to noticed that - that the attribute 'hint' overrode (is that a word?) the comments but failed on the other attributes. The method attributes are the same - only the hint can be overriden. Defining @returnFormat as a comment and attributes nets to the same error -
"It's a feature" - that's what I'll call it :D
@Jojo,
Hmm, I guess the docs are right... or rather, demonstrate the *only* override you can perform. I can't seem them explicitly say that anything can be overridden, other than in that one code snippet.
Somewhere, someone once said, "Good code is self documenting... "
I think this is one of the better features the CF team implemented... I don't know anyone who 'disagrees' with having well documented code... JavaDoc is by far one of my favorite features of Java... and ColdFusion...
I think the issue isn't documenting versus not documenting, but rather if documentation should impact how the code actually runs. To me, that is a sticking point. Nothing I write in my code comments should impact how the code actually behaves. It is a comment - not code - and for it to act otherwise is a mistake imo.
@Ray... 100%.
IMHO... Documentation should only document - nothing else. SRP.
On the one hand, I entirely agree with you guys - having the comments shouldn't change the way the function works. However, on the other hand, the non-comment way to do some of this stuff is just so unattractive that I think the comments are the lesser evil.
For things other than ReturnType, Access, and Arguments, you have to put the values in between the ")" and "{" ... which actually makes me feel a little weak in the knees, and not in the "Vin Diesel just walked by" kind of way :)
function foo() .... output = false .... { ... function body .... }
So for me, moving the [output=false] to the JavaDocs is lame, but still better than the above.