# groovydoc, the Groovy & Java documentation generator

version 5.0.0-alpha-1

GroovyDoc is a tool responsible for generating documentation from your code. It acts like the Javadoc tool in the Java world but is capable of handling both `groovy` and `java` files. The distribution comes with two ways of generating documentation: from command line or from Apache Ant. Other build tools like Maven or Gradle also offer wrappers for Groovydoc.

## 1. The groovydoc command line tool

The `groovydoc` command line can be invoked to generate groovydocs:

    groovydoc [options] [packagenames] [sourcefiles]

where options must be picked from the following table:

Short version | Long version | Description
--- | --- | ---
-author |  | Include @author paragraphs (currently not used)
-charset <charset> |  | Charset for cross-platform viewing of generated documentation
-classpath, -cp | --classpath | Specify where to find the class files - must be first argument
-d | --destdir <dir> | Destination directory for output files
| --debug | Enable debug output
-doctitle <html> |  | Include title for the overview page
-exclude <pkglist> |  | Specify a list of packages to exclude (separated by colons for all operating systems)
-fileEncoding <charset> |  | Charset for generated documentation files
-footer <html> |  | Include footer text for each page
-header <html> |  | Include header text for each page
-help | --help | Display help message
-nomainforscripts |  | Don’t include the implicit 'public static void main' method for scripts
-noscripts |  | Don’t process Groovy Scripts
-notimestamp |  | Don’t include timestamp within hidden comment in generated HTML
-noversionstamp |  | Don’t include Groovy version within hidden comment in generated HTML
-overview <file> |  | Read overview documentation from HTML file
-package |  | Show package/protected/public classes and members
-private |  | Show all classes and members
-protected |  | Show protected/public classes and members (default)
-public |  | Show only public classes and members
-quiet |  | Suppress superfluous output
-sourcepath <pathlist> |  | Specify where to find source files (dirs separated by platform path separator)
-stylesheetfile <path> |  | File to change style of the generated documentation
-verbose |  | Enable verbose output
| --version | Display the version
-windowtitle <text> |  | Browser window title for the documentation

## 2. The groovydoc Ant task

The `groovydoc` Ant task allows generating groovydocs from an Ant build.

### 2.1. Required taskdef

Assuming all the groovy jars you need are in my.classpath (this will be `groovy-VERSION.jar`, `groovy-ant-VERSION.jar`, `groovy-groovydoc-VERSION.jar` plus any modules and transitive dependencies you might be using) you will need to declare this task at some point in the build.xml prior to the groovydoc task being invoked.

    <taskdef name         = "groovydoc"
             classname    = "org.codehaus.groovy.ant.Groovydoc"
             classpathref = "my.classpath"/>

### 2.2. <groovydoc> Attributes

Attribute | Description | Required
--- | --- | ---
destdir | Location to store the class files. | Yes
sourcepath | The sourcepath to use. | No
packagenames | Comma separated list of package files (with terminating wildcard). | No
use | Create class and package usage pages. | No
windowtitle | Browser window title for the documentation (text). | No
doctitle | Include title for the package index(first) page (html-code). | No
header | Include header text for each page (html-code). | No
footer | Include footer text for each page (html-code). | No
overview | Read overview documentation from HTML file. | No
private | Show all classes and members (i.e. including private ones) if set to ``true''. | No

### 2.3. <groovydoc> Nested Elements

#### 2.3.1. link

Create link to groovydoc/javadoc output at the given URL.

Attribute | Description | Required
--- | --- | ---
packages | Comma separated list of package prefixes | Yes
href | Base URL of external site | Yes

#### 2.3.2. Example #1 - <groovydoc> Ant task

    <taskdef name           = "groovydoc"
             classname      = "org.codehaus.groovy.ant.Groovydoc"
             classpathref   = "path_to_groovy_all"/>

    <groovydoc destdir      = "${docsDirectory}/gapi"
               sourcepath   = "${mainSourceDirectory}"
               packagenames = "**.*"
               use          = "true"
               windowtitle  = "${title}"
               doctitle     = "${title}"
               header       = "${title}"
               footer       = "${docFooter}"
               overview     = "src/main/overview.html"
               private      = "false">
            <link packages="java.,org.xml.,javax.,org.xml." href="http://docs.oracle.com/javase/8/docs/api/"/>
            <link packages="org.apache.tools.ant."          href="http://docs.groovy-lang.org/docs/ant/api/"/>
            <link packages="org.junit.,junit.framework."    href="http://junit.org/junit4/javadoc/latest/"/>
            <link packages="groovy.,org.codehaus.groovy."   href="http://docs.groovy-lang.org/latest/html/api/"/>
            <link packages="org.codehaus.gmaven."           href="http://groovy.github.io/gmaven/apidocs/"/>
    </groovydoc>

#### 2.3.3. Example #2 - Executing <groovydoc> from Groovy

    def ant = new AntBuilder()
    ant.taskdef(name: "groovydoc", classname: "org.codehaus.groovy.ant.Groovydoc")
    ant.groovydoc(
        destdir      : "${docsDirectory}/gapi",
        sourcepath   : "${mainSourceDirectory}",
        packagenames : "**.*",
        use          : "true",
        windowtitle  : "${title}",
        doctitle     : "${title}",
        header       : "${title}",
        footer       : "${docFooter}",
        overview     : "src/main/overview.html",
        private      : "false") {
            link(packages:"java.,org.xml.,javax.,org.xml.",href:"http://docs.oracle.com/javase/8/docs/api/")
            link(packages:"groovy.,org.codehaus.groovy.",  href:"http://docs.groovy-lang.org/latest/html/api/")
            link(packages:"org.apache.tools.ant.",         href:"http://docs.groovy-lang.org/docs/ant/api/")
            link(packages:"org.junit.,junit.framework.",   href:"http://junit.org/junit4/javadoc/latest/")
            link(packages:"org.codehaus.gmaven.",          href:"http://groovy.github.io/gmaven/apidocs/")
    }

### 2.4. Custom templates

The `groovydoc` Ant task supports custom templates, but it requires two steps:

1. A custom groovydoc class

2. A new groovydoc task definition

#### 2.4.1. Custom Groovydoc class

The first step requires you to extend the `Groovydoc` class, like in the following example:

    package org.codehaus.groovy.tools.groovydoc;

    import org.codehaus.groovy.ant.Groovydoc;

    /**
     * Overrides GroovyDoc's default class template - for testing purpose only.
     */
    public class CustomGroovyDoc extends Groovydoc {

        @Override
        protected String[] getClassTemplates() {
            return new String[]{"org/codehaus/groovy/tools/groovydoc/testfiles/classDocName.html"};
        }
    }

You can override the following methods:

- `getClassTemplates` for class-level templates

- `getPackageTemplates` for package-level templates

- `getDocTemplates` for top-level templates

You can find the list of default templates in the `org.codehaus.groovy.tools.groovydoc.gstringTemplates.GroovyDocTemplateInfo` class.

#### 2.4.2. Using the custom groovydoc task

Once you’ve written the class, using it is just a matter of redefining the `groovydoc` task:

    <taskdef name           = "groovydoc"
             classname      = "org.codehaus.groovy.ant.CustomGroovyDoc"
             classpathref   = "path_to_groovy_all"/>

Please note that template customization is provided as is. APIs are subject to change, so you must consider this as a fragile feature.

## 3. GMavenPlus Maven Plugin

GMavenPlus is a Maven plugin with goals that support GroovyDoc generation.