Uploaded image for project: 'Groovy'
  1. Groovy
  2. GROOVY-6714

GroovyDoc omits and/or misplaces documentation for methods in .java files.

    XMLWordPrintableJSON

Details

    • Bug
    • Status: Closed
    • Major
    • Resolution: Fixed
    • 2.2.1, 2.3.0-beta-2
    • 2.3.0-rc-2, 2.2.3
    • GroovyDoc
    • None
    • 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)

    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
      

      Attachments

        1. groovydocbug.tgz
          1 kB
          James Durbin

        Issue Links

          Activity

            People

              paulk Paul King
              jdurbin James Durbin
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: