[GROOVY-6714] GroovyDoc omits and/or misplaces documentation for methods in .java files.

• Type: Bug
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Affects Version/s: 2.2.1, 2.3.0-beta-2
• Fix Version/s: 2.3.0-rc-2, 2.2.3
• Component/s: GroovyDoc
• Environment: Mac OS X 10.9.2; java version "1.7.0_21"; Java(TM) SE Runtime Environment (build 1.7.0_21-b12); Java HotSpot(TM) 64-Bit Server VM (build 23.21-b01, mixed mode)
• Assignee: Paul King
• Reporter: James Durbin
• Created: 16/Apr/14 20:29
• Updated: 28/Apr/14 19:30
• Resolved: 25/Apr/14 05:20

Description

GroovyDoc omits and/or misplaces documentation for some methods in java programs, making a hash of documentation output for mixed Java/Groovy projects.

Whether or not this bug presents itself depends in an odd way on the number of methods and the number of inline comments in those methods. It seems like it only appears when there are 3 or more methods and there are five or more inline comments in the first N-2 methods, where N is the number of methods.

A minimal example of a java program exhibiting the problem follows:

SmallestExample.java

/**
* This is the smallest example I could reproduce the error with.
*/
public class SmallestExample {
	  	
	/**
	* function1
	*/
	public int function1(){
		// comment1
		// comment2
		// comment3
		// comment4
		// comment5  (this comment breaks it)
		return(0);
	}
	
	/**
	*  function2
	*/
	public int function2(){		
		return(0);
	}
	
	/**
	* function3
	*/
	public int function3() {
		return(0);				
	}
}

Running GroovyDoc on this example will omit the documentation for function3. If there are more functions, the error can be induced by distributing the five or more inline comments in any way among the first few functions. If there are six or more functions in an example like this the documentation for the sixth function will appear in place of the documentation for the fifth function (in alphabetical doc order, not necessarily in file order) and the sixth function will have no documentation. The attached file includes examples of these cases. In a number of tests it did not seem to matter what the content of the functions were, how they were named, etc. Only the number of functions and the number of inline comments seemed to matter. On a large Java file (part of a mixed java/groovy project) this bug can make a total hash of the documentation, omitting documentation for many methods and, worse, swapping in the wrong documentation for many others.

GroovyDoc was run like this (where ~/local/groovy is the path to the groovy installation):

groovydoc -classpath ~/local/groovy/lib/ -d doc/ ./minexamples/*.java

Issue Links

• is related to: GROOVY-6254 groovydoc fails when java files start with single line comments