tracker issue : CF-3711305

select a category, or use search below
(searches all categories and all time range)
Title:

Javadoc-style comments don't handle line breaks like Java does

| View in Tracker

Status/Resolution/Reason: Closed/Fixed/

Reporter/Name(from Bugbase): Bradley Wood / Bradley Wood (Bradley Wood)

Created: 02/20/2014

Components: CFComponent

Versions: 11.0

Failure Type:

Found In Build/Fixed In Build: PublicBeta / 292274

Priority/Frequency: Major / All users will encounter

Locale/System: English / Windows 7 SP1 64-bit

Vote Count: 1

Listed in the version 2016.0.0.297996 Issues Fixed doc
Verification notes: verified_fixed on July 27, 2017 using build 2016.0.01.298513
Note, this is not a regression-- it's just always been parsed wrong.  It would be great to see the fix roll out in CF11 though.

I'm comparing the CFML behavior to Java since that's where we copied JavaDocs from.

Consider the following method:

/**
* Shutdown the native client connection
* 
* @timeout.hint The timeout in seconds, we default to 10 seconds
* 				so that we can do stuff
* 
* @return A reference to "this" CFC
*			so that it can work.
*/
CouchbaseClient function shutdown( numeric timeout=10 ){
	// implementation
	return this;
}

The parameter hint and @return annotation both have a line break. In Java, all text up until the next "@" would be part of the string. Instead, ColdFusion strips off the additional lines lines concatenates them to the method hint.

Here is what the javadoc documentation says about method comments (hint in CFML):

"The first line that begins with an "@" character ends the description. There is only one description block per doc comment; you cannot continue the description following block tags."

Also, here are example of valid JavaDocs that demonstrate line breaks used for parameter hints and @return annotations:

http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#examples

----------------------------- Additional Watson Details -----------------------------

Watson Bug ID:	3711305

External Customer Info:
External Company:  
External Customer Name: bradwood.com
External Customer Email:  
External Test Config: My Hardware and Environment details:

Attachments:

Comments:

To give this some context and explain why it matters, the ColdDoc tool is used to create Javadoc-style docs of ColdFusion components. It makes it a pain to specify good, descriptive documentation inline when line breaks can't be used. To see an example file that uses these docs heavily (for use with ColdDoc) look here: https://github.com/Ortus-Solutions/cfcouchbase-sdk/blob/master/cfcouchbase/CouchbaseClient.cfc Also, Railo has the same issue and a ticket has been entered here: https://issues.jboss.org/browse/RAILO-2917 Let the race begin!
Comment by External U.
13417 | February 20, 2014 11:34:42 PM GMT
This will most definitely help when generating docs
Vote by External U.
13422 | February 21, 2014 12:13:47 AM GMT
Any status on this. Sadly, Railo hasn't fixed their identical bug yet so that means there's still time for you to beat them to the punch!
Comment by External U.
13418 | July 18, 2014 01:08:53 PM GMT
This is fixed in coldfusion next release.Comments will handle line break now. Closing this bug.
Comment by Poonam J.
13419 | June 17, 2015 03:34:06 AM GMT
It looks like we might need to dial back the solution to only apply to argument hints and @return annotations. It turns out the extra whitespace is problematic for frameworks that read custom annotations like /** * @paramName.inject coldbox */ since extra white space now gets appended there. Please see my thread "ColdBox 4.1 not working" in the Prerelease "Raijin Bug Discussion".
Comment by External U.
13420 | July 11, 2015 08:53:30 AM GMT
Verified this is fixed in CF2016 Update 1 (build 2016.0.01.298513). Thanks!, -Aaron
Comment by Aaron N.
13421 | July 27, 2017 07:31:04 AM GMT