subprojects/groovy-groovydoc/src/spec/doc/groovydoc.adoc - groovy - Git at Google

 //////////////////////////////////////////

   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.

 //////////////////////////////////////////

 = groovydoc, the Groovy & Java documentation generator

 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 <<Groovydoc-CommandLine,command line>> or from <<Groovydoc-Ant,Apache Ant>>. Other build tools
 like Maven or Gradle also offer wrappers for Groovydoc.

 [[Groovydoc-CommandLine]]
 == 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:

 [cols="2,2,5",options="header,footer"]
 |=======================================================================
 |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
 |=======================================================================

 [[Groovydoc-Ant]]
 == The groovydoc Ant task

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

 [[ThegroovydocAnttask-Requiredtaskdef]]
 === 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.

 [source,xml]
 -----------------------------------------------------------
 <taskdef name         = "groovydoc"
          classname    = "org.codehaus.groovy.ant.Groovydoc"
          classpathref = "my.classpath"/>
 -----------------------------------------------------------

 [[ThegroovydocAnttask-groovydocAttributes]]
 === <groovydoc> Attributes

 [cols="1,2,1",options="header,footer"]
 |=======================================================================
 |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
 |=======================================================================

 [[ThegroovydocAnttask-groovydocNestedElements]]
 === <groovydoc> Nested Elements

 [[ThegroovydocAnttask-link]]
 ==== link

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

 [cols="<,<,<",options="header,footer"]
 |=======================================================
 |Attribute |Description |Required
 |packages |Comma separated list of package prefixes |Yes
 |href |Base URL of external site |Yes
 |=======================================================

 [[ThegroovydocAnttask-Example1-groovydocAnttask]]
 ==== Example #1 - <groovydoc> Ant task

 [source,xml]
 ----------------------------------------------------------------------------------------------------------------
 <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>
 ----------------------------------------------------------------------------------------------------------------

 [[ThegroovydocAnttask-Example2-ExecutinggroovydocfromGroovy]]
 ==== Example #2 - Executing <groovydoc> from Groovy

 [source,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/")
 }
 --------------------------------------------------------------------------------------------------------------

 === Custom templates

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

 . A custom groovydoc class
 . A new groovydoc task definition

 ==== Custom Groovydoc class

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

 [source,java]
 ----
 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.

 ==== Using the custom groovydoc task

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

 [source,xml]
 ----
 <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.

 [[Groovydoc-GMavenPlus]]
 == GMavenPlus Maven Plugin
 https://github.com/groovy/GMavenPlus[GMavenPlus] is a Maven plugin with goals that
 support GroovyDoc generation.
	//////////////////////////////////////////

	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.

	//////////////////////////////////////////

	= groovydoc, the Groovy & Java documentation generator

	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 <<Groovydoc-CommandLine,command line>> or from <<Groovydoc-Ant,Apache Ant>>. Other build tools
	like Maven or Gradle also offer wrappers for Groovydoc.

	[[Groovydoc-CommandLine]]
	== 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:

	[cols="2,2,5",options="header,footer"]
	\|=======================================================================
	\|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
	\|=======================================================================

	[[Groovydoc-Ant]]
	== The groovydoc Ant task

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

	[[ThegroovydocAnttask-Requiredtaskdef]]
	=== 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.

	[source,xml]
	-----------------------------------------------------------
	<taskdef name = "groovydoc"
	classname = "org.codehaus.groovy.ant.Groovydoc"
	classpathref = "my.classpath"/>
	-----------------------------------------------------------

	[[ThegroovydocAnttask-groovydocAttributes]]
	=== <groovydoc> Attributes

	[cols="1,2,1",options="header,footer"]
	\|=======================================================================
	\|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
	\|=======================================================================

	[[ThegroovydocAnttask-groovydocNestedElements]]
	=== <groovydoc> Nested Elements

	[[ThegroovydocAnttask-link]]
	==== link

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

	[cols="<,<,<",options="header,footer"]
	\|=======================================================
	\|Attribute \|Description \|Required
	\|packages \|Comma separated list of package prefixes \|Yes
	\|href \|Base URL of external site \|Yes
	\|=======================================================

	[[ThegroovydocAnttask-Example1-groovydocAnttask]]
	==== Example #1 - <groovydoc> Ant task

	[source,xml]
	----------------------------------------------------------------------------------------------------------------
	<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>
	----------------------------------------------------------------------------------------------------------------

	[[ThegroovydocAnttask-Example2-ExecutinggroovydocfromGroovy]]
	==== Example #2 - Executing <groovydoc> from Groovy

	[source,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/")
	}
	--------------------------------------------------------------------------------------------------------------

	=== Custom templates

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

	. A custom groovydoc class
	. A new groovydoc task definition

	==== Custom Groovydoc class

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

	[source,java]
	----
	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.

	==== Using the custom groovydoc task

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

	[source,xml]
	----
	<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.

	[[Groovydoc-GMavenPlus]]
	== GMavenPlus Maven Plugin
	https://github.com/groovy/GMavenPlus[GMavenPlus] is a Maven plugin with goals that
	support GroovyDoc generation.