tessl/maven-org-apache-groovy--groovy-groovydoc

A documentation generation tool for Groovy code, part of the Apache Groovy programming language suite

—

Pending

Overview

Eval results

Files

Documentation Generation

Name: tessl/maven-org-apache-groovy--groovy-groovydoc
Author: tessl

The documentation generation capability provides the core functionality for creating Groovy documentation from source code. This includes parsing source files, extracting documentation comments, and building the documentation model.

Core API

GroovyDocTool

The primary class for documentation generation operations.

public class GroovyDocTool

Constructors

// Basic constructor for simple documentation generation
public GroovyDocTool(String[] sourcepaths)

// Constructor with template support
public GroovyDocTool(ResourceManager resourceManager, String[] sourcepaths, String classTemplate)

// Full constructor with all configuration options
public GroovyDocTool(ResourceManager resourceManager, String[] sourcepaths, 
                     String[] docTemplates, String[] packageTemplates, 
                     String[] classTemplates, List<LinkArgument> links, 
                     String javaVersion, Properties properties)

Key Methods

// Add source files to be processed
public void add(List<String> filenames)

// Get the complete documentation model
public GroovyRootDoc getRootDoc()

// Generate final documentation output
public void renderToOutput(OutputTool output, String destdir)

Usage Examples

Basic Documentation Generation

import org.codehaus.groovy.tools.groovydoc.GroovyDocTool;
import org.codehaus.groovy.tools.groovydoc.FileOutputTool;
import java.util.Arrays;
import java.util.List;

// Set up source paths
String[] sourcePaths = {
    "src/main/groovy",
    "src/main/java"
};

// Create the documentation tool
GroovyDocTool tool = new GroovyDocTool(sourcePaths);

// Add specific source files
List<String> sourceFiles = Arrays.asList(
    "com/example/GroovyClass.groovy",
    "com/example/JavaClass.java",
    "com/example/interfaces/MyInterface.groovy"
);
tool.add(sourceFiles);

// Generate documentation
FileOutputTool output = new FileOutputTool();
tool.renderToOutput(output, "build/docs/groovydoc");

Advanced Configuration

import org.codehaus.groovy.tools.groovydoc.*;
import java.util.Properties;
import java.util.List;
import java.util.Arrays;

// Set up resource manager for custom templates
ResourceManager resourceManager = new FileSystemResourceManager("templates");

// Configure templates
String[] docTemplates = {"overview-frame.html", "allclasses-frame.html"};
String[] packageTemplates = {"package-frame.html", "package-summary.html"};
String[] classTemplates = {"class.html"};

// Configure external links
List<LinkArgument> links = Arrays.asList(
    new LinkArgument("http://docs.oracle.com/javase/8/docs/api/", "java.*,javax.*"),
    new LinkArgument("http://docs.groovy-lang.org/latest/html/api/", "groovy.*")
);

// Set up properties
Properties props = new Properties();
props.setProperty("windowTitle", "My Project API");
props.setProperty("docTitle", "My Project Documentation");

// Create fully configured tool
GroovyDocTool tool = new GroovyDocTool(
    resourceManager,
    new String[]{"src/main/groovy", "src/main/java"},
    docTemplates,
    packageTemplates, 
    classTemplates,
    links,
    "1.8", // Java version
    props
);

// Add source files and generate
tool.add(Arrays.asList("com/example/*.groovy"));
tool.renderToOutput(new FileOutputTool(), "docs/api");

Working with the Documentation Model

import org.codehaus.groovy.groovydoc.*;

// Generate and access the documentation model
GroovyDocTool tool = new GroovyDocTool(sourcePaths);
tool.add(sourceFiles);

// Access the root documentation object
GroovyRootDoc rootDoc = tool.getRootDoc();

// Iterate through all documented classes
GroovyClassDoc[] allClasses = rootDoc.classes();
for (GroovyClassDoc classDoc : allClasses) {
    System.out.println("Class: " + classDoc.qualifiedName());
    
    // Access methods
    GroovyMethodDoc[] methods = classDoc.methods();
    for (GroovyMethodDoc method : methods) {
        System.out.println("  Method: " + method.name() + method.signature());
    }
    
    // Access fields
    GroovyFieldDoc[] fields = classDoc.fields();
    for (GroovyFieldDoc field : fields) {
        System.out.println("  Field: " + field.name() + " : " + field.type().typeName());
    }
}

Configuration Classes

LinkArgument

Configuration for external documentation links.

public class LinkArgument {
    public String getHref()                    // Get link URL
    public void setHref(String href)           // Set link URL
    public String getPackages()                // Get comma-separated packages
    public void setPackages(String packages)   // Set packages to link
}

Usage example:

LinkArgument link = new LinkArgument();
link.setHref("http://docs.groovy-lang.org/latest/html/api/");
link.setPackages("groovy.*,org.codehaus.groovy.*");

Error Handling

The documentation generation process may encounter various issues with source files or configuration. Errors are typically reported through the logging system and may result in incomplete documentation generation.

Common issues include:

Invalid source file paths
Syntax errors in source files
Missing template files
I/O errors during output generation

To monitor for errors, check the logging output during generation:

// The tool uses internal logging - monitor console output for warnings/errors
GroovyDocTool tool = new GroovyDocTool(sourcePaths);
tool.add(sourceFiles);
// Check console for any error messages during processing
tool.renderToOutput(output, outputDir);

Install with Tessl CLI

npx tessl i tessl/maven-org-apache-groovy--groovy-groovydoc

docs