Custom GroovyDocTool not finding anything - groovy

Question

I'm having difficulty using GroovyDocTool.
No matter what paths I pass into it, my rootDoc does not resolve to any packages, classes, or methods. I have to assume I'm just passing in the wrong paths, but for the life of me can't figure out what to pass.
class TestGroovyDoclet extends GroovyDocTool{
public TestGroovyDoclet() {
super([
'~/ ... /src/'
,'/home/ ... /src/ ... /Sample/'
,'/home/ ... /src/ ... /Sample/Results.groovy'
]);
}
public void Execute(){
System.out.println('Begin Processing Javadoc');
System.out.format(' p %d\n', rootDoc.specifiedPackages().length);
System.out.format(' c %d\n', rootDoc.classes().length);
System.out.println('Finished Processing Javadoc');
}
public static void main(String[] args){
(new TestGroovyDoclet()).with{
it.Execute();
}
}
}
What are considered valid parameters to pass into the GroovyRootDocBuilder?

Answer 1

The authors of GroovyDoc appear to have intended for its use from Ant. This means that there is no means to look up the files to be processed, since you should already know what files you are processing. The consumer must specify the individual files to be processed, and call buildPath to actually process the files. (see override of buildPath)
For those only wanting to interact with the Document Tree, GroovyDocTool is really of no value, and users would likely be better extending GroovyRootDocBuilder which actually contains the meat of the processing. If you are doing this, you may as well re-write the constructor to hide away GroovyDocTool altogether. (see the new Constructor)
class TestGroovyDoclet extends GroovyRootDocBuilder{
protected def sourcepaths = [];
public TestGroovyDoclet() {
//HARDCODE: some test values for my testing
this([
'~/ ... /src/'
,'/home/ ... /src/ ... /Sample/'
,'/home/ ... /src/ ... /Sample/Results.groovy'
]);
}
public TestGroovyDoclet(String[] sourcepaths) {
//hide the unused GroovyDocTool
super(new GroovyDocTool(), sourcepaths, new ArrayList<LinkArgument>(), new Properties());
this.sourcepaths = sourcepaths;
}
/**
* Builds the tree by recursively searching for files
* <p>
* It is likely useful to override the original buildTree
* method as well to put some safeties in place. The parsing
* routines do not do a lot of validation. For those of us
* inheritting, it would be a good idea to override build
* tree ot sanitize the input list as much as possible.
* </p>
*/
#Override
public void buildTree(){
def list = [];
// loop through the sourcepaths to recursively find the files
for (String sourcepath : sourcepaths) {
def root = new File(sourcepath);
if(root.exists()){
if(root.isFile()){
list << root.absolutePath;
}
else{
root.eachFileRecurse (FileType.FILES) { file -> list << file.absolutePath; };
}
}
}
buildTree(list);
}
/**
* Method to actually do the processing. Sample only, does not demonstrate anything useful.
*/
public void Execute(){
buildTree();
System.out.println('Begin Processing GroovyDoc');
System.out.format(' p %d\n', rootDoc.specifiedPackages().length);
//System.out.format(' c %d\n', rootDoc.classes().length);
int count = 0;
for(def p : rootDoc.specifiedPackages()){
count += p.allClasses().length;
}
System.out.format(' c %d\n', count);
System.out.println('Finished Processing GroovyDoc');
}
public static void main(String[] args){
(new TestGroovyDoclet()).with{
it.Execute();
}
}
}
The above code is not perfect, and not exactly what I came up with; rather the code is meant to highlight a few of the faulty assumptions contained in the OP, and mechanisms to work around them. It is not gauranteed to compile since it just cut/pastes elements of a larger re-write.
Weirdness:
Interestingly GroovyRootDoc.classes always returns null (unsure why). It was necessary to loop through each package, and inspect the classes that are a subset of each. This was surprising, but the desired usage anyway.
The code above only worked on groovy files, not java. I think GroovyDoc choked on some java1.8 syntax (but I'm not sure).