Index: src/test/groovy/org/gradle/api/tasks/javadoc/JavadocTest.java =================================================================== --- src/test/groovy/org/gradle/api/tasks/javadoc/JavadocTest.java (revision 1196) +++ src/test/groovy/org/gradle/api/tasks/javadoc/JavadocTest.java (working copy) @@ -77,7 +77,38 @@ one(dependencyManager).resolveTask(AbstractTaskTest.TEST_TASK_NAME); will(returnValue(classpath)); - one(antJavadoc).execute(srcDirs, destDir, classpath, null, null, EMPTY_LIST, EMPTY_LIST, false, getProject().getAnt()); + one(antJavadoc).execute(srcDirs, // sourceDirs + destDir, // destDir + classpath, // classpathFiles + null, // windowTitle + null, // overview + null, // access + null, // header + null, // footer + null, // locale + null, // encoding + false, // version + false, // use + false, // splitIndex + false, // author + false, // breakIterator + false, // defaultExcludes + false, // useExternalFile + false, // linkSource + null, // linkOffline + null, // additionalParam + null, // doclet + EMPTY_LIST, // docletPath + EMPTY_LIST, // classPath + null, // link + null, // group + null, // stylesheetFile + null, // helpFile + null, // maxMemory + EMPTY_LIST, // includes + EMPTY_LIST, // excludes + false, // verbose + getProject().getAnt()); // ant }}); task.execute(); @@ -97,7 +128,38 @@ one(dependencyManager).resolveTask(AbstractTaskTest.TEST_TASK_NAME); will(returnValue(classpath)); - one(antJavadoc).execute(srcDirs, destDir, classpath, null, null, EMPTY_LIST, EMPTY_LIST, false, getProject().getAnt()); + one(antJavadoc).execute(srcDirs, // sourceDirs + destDir, // destDir + classpath, // classpathFiles + null, // windowTitle + null, // overview + null, // access + null, // header + null, // footer + null, // locale + null, // encoding + false, // version + false, // use + false, // splitIndex + false, // author + false, // breakIterator + false, // defaultExcludes + false, // useExternalFile + false, // linkSource + null, // linkOffline + null, // additionalParam + null, // doclet + EMPTY_LIST, // docletPath + EMPTY_LIST, // classPath + null, // link + null, // group + null, // stylesheetFile + null, // helpFile + null, // maxMemory + EMPTY_LIST, // includes + EMPTY_LIST, // excludes + false, // verbose + getProject().getAnt()); // ant will(throwException(failure)); }}); @@ -124,7 +186,38 @@ one(dependencyManager).resolveTask(AbstractTaskTest.TEST_TASK_NAME); will(returnValue(classpath)); - one(antJavadoc).execute(srcDirs, destDir, classpath, "title", "max-memory", EMPTY_LIST, EMPTY_LIST, true, getProject().getAnt()); + one(antJavadoc).execute(srcDirs, // sourceDirs + destDir, // destDir + classpath, // classpathFiles + "title", // windowTitle + null, // overview + null, // access + null, // header + null, // footer + null, // locale + null, // encoding + false, // version + false, // use + false, // splitIndex + false, // author + false, // breakIterator + false, // defaultExcludes + false, // useExternalFile + false, // linkSource + null, // linkOffline + null, // additionalParam + null, // doclet + EMPTY_LIST, // docletPath + EMPTY_LIST, // classPath + null, // link + null, // group + null, // stylesheetFile + null, // helpFile + "max-memory", // maxMemory + EMPTY_LIST, // includes + EMPTY_LIST, // excludes + true, // verbose + getProject().getAnt()); // ant }}); task.execute(); @@ -143,7 +236,38 @@ one(dependencyManager).resolveTask(AbstractTaskTest.TEST_TASK_NAME); will(returnValue(classpath)); - one(antJavadoc).execute(srcDirs, destDir, classpath, null, null, WrapUtil.toList("include"), WrapUtil.toList("exclude"), false, getProject().getAnt()); + one(antJavadoc).execute(srcDirs, // sourceDirs + destDir, // destDir + classpath, // classpathFiles + null, // windowTitle + null, // overview + null, // access + null, // header + null, // footer + null, // locale + null, // encoding + false, // version + false, // use + false, // splitIndex + false, // author + false, // breakIterator + false, // defaultExcludes + false, // useExternalFile + false, // linkSource + null, // linkOffline + null, // additionalParam + null, // doclet + EMPTY_LIST, // docletPath + EMPTY_LIST, // classPath + null, // link + null, // group + null, // stylesheetFile + null, // helpFile + null, // maxMemory + WrapUtil.toList("include"), // includes + WrapUtil.toList("exclude"), // excludes + false, // verbose + getProject().getAnt()); // ant }}); task.execute(); Index: src/main/groovy/org/gradle/api/plugins/JavaPluginConvention.groovy =================================================================== --- src/main/groovy/org/gradle/api/plugins/JavaPluginConvention.groovy (revision 1196) +++ src/main/groovy/org/gradle/api/plugins/JavaPluginConvention.groovy (working copy) @@ -44,6 +44,8 @@ String distsDirName String docsDirName String javadocDirName + String javadocVerbose + String javadocMaxMemory String testResultsDirName String reportsDirName String webAppDirName @@ -78,6 +80,7 @@ distsDirName = 'distributions' docsDirName = 'docs' javadocDirName = 'javadoc' + javadocVerbose = false reportsDirName = 'reports' uploadLibsPomDirName = 'libs-poms' uploadDistsPomDirName = 'dists-poms' Index: src/main/groovy/org/gradle/api/tasks/javadoc/Javadoc.java =================================================================== --- src/main/groovy/org/gradle/api/tasks/javadoc/Javadoc.java (revision 1196) +++ src/main/groovy/org/gradle/api/tasks/javadoc/Javadoc.java (working copy) @@ -44,6 +44,34 @@ private String title; + private File overview; + private String access; + private String header; + private String footer; + private String locale; + private String encoding; + private boolean version; + private boolean use; + private boolean splitIndex; + private boolean author; + private File stylesheetFile; + private File helpFile; + private boolean breakIterator; + private boolean defaultExcludes; + private boolean useExternalFile; + private boolean linkSource; + private String linkOffline; + private String additionalParam; + private String doclet; + // + // The doclet path becomes type: org.apache.tools.ant.types.Path, + // so build.gradle users say: docletpath = [ "/moo/cow", "/foo/bar" ] + // + private List docletPath = new ArrayList(); + private List classPath = new ArrayList(); + private String link; + private String group; + private String maxMemory; private List includes = new ArrayList(); @@ -68,8 +96,39 @@ private void generate() { List existingSourceDirs = existentDirsFilter.checkDestDirAndFindExistingDirsAndThrowStopActionIfNone(getDestinationDir(), getSrcDirs()); try { - antJavadoc.execute(existingSourceDirs, getDestinationDir(), getClasspath(), getTitle(), getMaxMemory(), getIncludes(), getExcludes(), - verbose, getProject().getAnt()); + antJavadoc.execute(existingSourceDirs, // ::TODO:: switch to 'options' object. + getDestinationDir(), + getClasspath(), + getTitle(), + getOverview(), + getAccess(), + getHeader(), + getFooter(), + getLocale(), + getEncoding(), + getVersion(), + getUse(), + getSplitIndex(), + getAuthor(), + getBreakIterator(), + getDefaultExcludes(), + getUseExternalFile(), + getLinkSource(), + getLinkOffline(), + getAdditionalParam(), + getDoclet(), + getDocletPath(), + getClassPath(), + getLink(), + getGroup(), + getStylesheetFile(), + getHelpFile(), + getMaxMemory(), + getIncludes(), + getExcludes(), + verbose, + getProject().getAnt()); + } catch (BuildException e) { throw new GradleException("Javadoc generation failed.", e); } @@ -117,10 +176,10 @@ } /** - * Returns the amount of memory allocated to this task. + * Returns the amount of memory allocated to this task, possibly null. */ public String getMaxMemory() { - return maxMemory; + return (String) conv(maxMemory, "javadocMaxMemory"); } /** @@ -138,7 +197,7 @@ * @return The title, possibly null. */ public String getTitle() { - return (String) conv(title, "title"); + return (String) conv(title, "javadocTitle"); } /** @@ -148,7 +207,408 @@ this.title = title; } + /** + *

Returns the overview for the generated documentation.

+ * + * @return The overview, possibly null. + */ + public File getOverview() { + return (File) conv(overview, "javadocOverview"); + } + + /** + *

Sets the overview page for the generated documentation.

+ */ + public void setOverview(File overview) { + this.overview = overview; + } + + + + /** + *

Returns the access level for the generated documentation.

+ * Possible values are: 'public', 'private', or 'protected'.
+ * + * @return The access level, possibly null. + */ + public String getAccess() { + return (String) conv(access, "javadocAccess"); + } + + /** + *

Sets the access level for the generated documentation.

+ * Possible values are: 'public', 'private', or 'protected'.
+ */ + public void setAccess(String access) { + this.access = access; + } + + + + /** + *

Returns the header for the generated documentation.

+ * + * @return The header, possibly null + */ + public String getHeader() { + return (String) conv(header, "javadocHeader"); + } + + /** + *

Sets the header for the generated documentation.

+ */ + public void setHeader(String header) { + this.header = header; + } + + + + /** + *

Returns the footer for the generated documentation.

+ * + * @return The footer, possibly null + */ + public String getFooter() { + return (String) conv(footer, "javadocFooter"); + } + + /** + *

Sets the footer for the generated documentation.

+ */ + public void setFooter(String footer) { + this.footer = footer; + } + + + /** + *

Returns the locale used for the generated documentation.

+ * + * @return The locale, possibly null + */ + public String getLocale() { + return (String) conv(locale, "javadocLocale"); + } + + /** + *

Sets the locale to use for the generated documentation.

+ */ + public void setLocale(String locale) { + this.locale = locale; + } + + + /** + *

Returns the encoding used for the generated documentation.

+ * + * @return The encoding, possibly null + */ + public String getEncoding() { + return (String) conv(encoding, "javadocEncoding"); + } + + /** + *

Sets the encoding used for the generated documentation.

+ */ + public void setEncoding(String encoding) { + this.encoding = encoding; + } + + + /** + *

Returns whether the version should be included in the generated documentation.

+ * + * @return The version tag setting, possibly null + */ + public Boolean getVersion() { + return (Boolean) conv(version, "javadocVersion"); + } + + /** + *

Sets whether the version tag will be included in the generated documentation.

+ */ + public void setVersion(Boolean version) { + this.version = version; + } + + + /** + *

Returns whether the "use" page should be generated for each page in the package

+ * + * @return The use, possibly null + */ + public Boolean getUse() { + return (Boolean) conv(use, "javadocUse"); + } + + /** + *

Sets whether the "use" page should be generated for each page in the package

+ */ + public void setUse(boolean use) { + this.use = use; + } + + + /** + *

Returns whether the index should be split into a file per letter

+ * + * @return The splitIndex, possibly null + */ + public Boolean getSplitIndex() { + return (Boolean) conv(splitIndex, "javadocSplitIndex"); + } + + /** + *

Sets whether the index should be split into a file per letter

+ */ + public void setSplitIndex(boolean splitIndex) { + this.splitIndex = splitIndex; + } + + /** + *

Returns whether author tag is included in generated files.

+ * + * @return The author, possibly null + */ + public Boolean getAuthor() { + return (Boolean) conv(author, "javadocAuthor"); + } + + /** + *

Sets whether the author tag should be included in generated files.

+ */ + public void setAuthor(boolean author) { + this.author = author; + } + + + + + /** + *

Returns the stylesheetFile for the generated documentation.

+ * + * @return The stylesheetFile, possibly null. + */ + public File getStylesheetFile() { + return (File) conv(stylesheetFile, "javadocStylesheetFile"); + } + + /** + *

Sets the stylesheetFile page for the generated documentation.

+ */ + public void setStylesheetFile(File stylesheetFile) { + this.stylesheetFile = stylesheetFile; + } + + + /** + *

Returns the helpFile for the generated documentation.

+ * + * @return The helpFile, possibly null. + */ + public File getHelpFile() { + return (File) conv(helpFile, "javadocHelpFile"); + } + + /** + *

Sets the helpFile page for the generated documentation.

+ */ + public void setHelpFile(File helpFile) { + this.helpFile = helpFile; + } + + + + /** + *

Returns whether the new break iterator algorithm is used.

+ * + * @return The breakIterator, possibly null + */ + public Boolean getBreakIterator() { + return (Boolean) conv(breakIterator, "javadocBreakIterator"); + } + + /** + *

Sets whether the new break iterator algortithm is used.

+ */ + public void setBreakIterator(boolean breakIterator) { + this.breakIterator = breakIterator; + } + + + /** + *

Returns whether default excludes should be used.

+ * + * @return The defaultExcludes, possibly null + */ + public Boolean getDefaultExcludes() { + return (Boolean) conv(defaultExcludes, "javadocDefaultExcludes"); + } + + /** + *

Set whether default excludes should be used.

+ */ + public void setDefaultExcludes(boolean defaultExcludes) { + this.defaultExcludes = defaultExcludes; + } + + + /** + *

Returns whether javadoc files list is written to a temporary file.

+ * + * @return The useExternalFile, possibly null + */ + public Boolean getUseExternalFile() { + return (Boolean) conv(useExternalFile, "javadocUseExternalFile"); + } + + /** + *

Set whether an external temporary file should be used when invoking javadoc.

+ */ + public void setUseExternalFile(boolean useExternalFile) { + this.useExternalFile = useExternalFile; + } + + + /** + *

Returns whether hyperlinks will be generated to source files.

+ * + * @return The linkSource, possibly null + */ + public Boolean getLinkSource() { + return (Boolean) conv(linkSource, "javadocLinkSource"); + } + + /** + *

Sets whether hyperlinks will be generated to source files.

+ */ + public void setLinkSource(boolean linkSource) { + this.linkSource = linkSource; + } + + + /** + *

Link to docs at <url> using package list at <url2>

+ * + * @return The linkOffline, possibly null + */ + public String getLinkOffline() { + return (String) conv(linkOffline, "javadocLinkOffline"); + } + + /** + *

Link to docs at <url> using package list at <url2>

+ */ + public void setLinkOffline(String url) { + this.linkOffline = url; + } + + + /** + *

Fetches additional parameters set for javadoc (useful for doclets).

+ * + * @return The additionalParam, possibly null + */ + public String getAdditionalParam() { + return (String) conv(additionalParam, "javadocAdditionalParam"); + } + + /** + *

Sets additional parameters for javadoc (useful for doclets).

+ */ + public void setAdditionalParam(String additionalParam) { + this.additionalParam = additionalParam; + } + + + /** + *

Gets name of class file used in generating documentation (e.g.: com.sun.tools.doclets.mif.MIFDoclet)

+ * + * @return The doclet, possibly null + */ + public String getDoclet() { + return (String) conv(doclet, "javadocDoclet"); + } + + /** + *

Specifies the class that starts the doclet (e.g.: com.sun.tools.doclets.mif.MIFDoclet).

+ */ + public void setDoclet(String classname) { + this.doclet = classname; + } + + + /** + *

Fetches URL to which javadocs links are made.

+ * + * @return The link, possibly null + */ + public String getLink() { + return (String) conv(link, "javadocLink"); + } + + /** + *

Create links to javadoc output at the given URL.

+ */ + public void setLink(String url) { + this.link = url; + } + + + + /** + *

Fetches specified packages grouped together in overview page.

+ * + * @return The group, possibly null + */ + public String getGroup() { + return (String) conv(group, "javadocGroup"); + } + + /** + *

Group specified packages together in overview page.

+ */ + public void setGroup(String src) { + this.group = src; + } + + + /** + *

Gets the classpath used by the doclet.

+ * + */ + public List getDocletPath() { + return (List) conv(docletPath, "docletPath"); + } + + /** + *

Sets the classpath used by the doclet.

+ */ + public void setDocletPath(List docletPath) { + this.docletPath = new ArrayList(docletPath); + } + + + + + /** + *

Gets path were user classfiles are found.

+ * + */ + public List getClassPath() { + return (List) conv(classPath, "classPath"); + } + + /** + *

Sets where to find user class files.

+ */ + public void setClassPath(List classPath) { + this.classPath = new ArrayList(classPath); + } + + + + /** *

Adds include patterns to use to select the java source files to be documented.

* * @param includes A set of ant patterns. @@ -207,12 +667,12 @@ } /** - * Returns whether javadoc generation is accompanied by verbose output. + * Returns whether javadoc generation is accompanied by verbose output (default: false) * * @see #setVerbose(boolean) */ - public boolean isVerbose() { - return verbose; + public Boolean getVerbose() { + return (Boolean) conv(verbose, "javadocVerbose"); } /** Index: src/main/groovy/org/gradle/api/tasks/javadoc/AntJavadoc.groovy =================================================================== --- src/main/groovy/org/gradle/api/tasks/javadoc/AntJavadoc.groovy (revision 1196) +++ src/main/groovy/org/gradle/api/tasks/javadoc/AntJavadoc.groovy (working copy) @@ -20,14 +20,82 @@ * @author Hans Dockter */ class AntJavadoc { - void execute(List sourceDirs, File destDir, List classpathFiles, String windowTitle, String maxMemory, - List includes, List excludes, boolean verbose, AntBuilder ant) { + void execute(List sourceDirs, + File destDir, + List classpathFiles, + String windowTitle, + File overview, + String access, + String header, + String footer, + String locale, + String encoding, + Boolean version, + Boolean use, + Boolean splitIndex, + Boolean author, + Boolean breakIterator, + Boolean defaultExcludes, + Boolean useExternalFile, + Boolean linkSource, + String linkOffline, + String additionalParam, + String doclet, + List docletPath, + List classPath, + String link, + String group, + File stylesheetFile, + File helpFile, + String maxMemory, + List includes, + List excludes, + Boolean verbose, + AntBuilder ant) { Map otherArgs = [:] if (maxMemory) {otherArgs.maxmemory = maxMemory} if (windowTitle) { otherArgs.windowtitle = windowTitle otherArgs.doctitle = "

$windowTitle

" } + if (overview) { otherArgs.overview = overview } + if (access) { otherArgs.access = access } + if (header) { otherArgs.header = header } + if (footer) { otherArgs.footer = footer } + if (locale) { otherArgs.locale = locale } + if (encoding) { otherArgs.encoding = encoding } + if (version) { otherArgs.version = version } + if (use) { otherArgs.use = use } + if (splitIndex) { otherArgs.splitIndex = splitIndex } + if (author) { otherArgs.author = author } + if (stylesheetFile) { otherArgs.stylesheetFile = stylesheetFile } + if (helpFile) { otherArgs.helpFile = helpFile } + if (breakIterator) { otherArgs.breakIterator = breakIterator } + if (defaultExcludes) { otherArgs.defaultExcludes = defaultExcludes } + if (useExternalFile) { otherArgs.useExternalFile = useExternalFile } + if (linkSource) { otherArgs.linkSource = linkSource } + if (linkOffline) { otherArgs.linkOffline = linkOffline } + if (additionalParam) { otherArgs.additionalParam = additionalParam } + if (doclet) { otherArgs.doclet = doclet } + if (link) { otherArgs.link = link } + if (group) { otherArgs.group = group } + + + // Construct org.apache.tools.ant.types.Path + // In the build.gradle file, you'll see code like this: + // docletpath = [ "/moo/cow", "/foo/bar" ] + // + if ( docletPath ) + { + otherArgs.docletPath = + ant.path { docletPath.each { pathelement(location: it) } } + } + if ( classPath ) + { + otherArgs.classPath = + ant.path { classPath.each { pathelement(location: it) } } + } + ant.javadoc([destdir: destDir, failonerror: true, verbose: verbose] + otherArgs) { sourceDirs.each { fileset(dir: it) { Index: src/main/groovy/org/gradle/api/tasks/testing/AntJunit.groovy =================================================================== --- src/main/groovy/org/gradle/api/tasks/testing/AntJunit.groovy (revision 1196) +++ src/main/groovy/org/gradle/api/tasks/testing/AntJunit.groovy (working copy) @@ -68,7 +68,7 @@ } } ant.junitreport(todir: testResultsDir.absolutePath) { - fileset(dir: testResultsDir.absolutePath, includes: '*.xml') + fileset(dir: testResultsDir.absolutePath, includes: '*.xml', excludes: 'TESTS-TestSuites.xml') report(todir: testReportDir.absolutePath) } } Index: src/docs/userguide/javaPlugin.tex =================================================================== --- src/docs/userguide/javaPlugin.tex (revision 1196) +++ src/docs/userguide/javaPlugin.tex (working copy) @@ -3,7 +3,8 @@ \label{cha:the_java_plugin} Table \ref{javalayout} shows the default project layout assumed by the Java Plugin. This is configurable via the convention object. Table \ref{javatasks} shows the tasks added by the Java Plugin. These tasks constitute a lifecycle for Java builds. Table \ref{javaconventionDir} and Table \ref{javaconventionNonDir} shows the most important properties of the convention object of the Java plugin.\footnote{The \emph{buildDir} property is a property of the project object. It defaults to \texttt{build}.} Gradle's conventions contain a convention for the directory hierarchy as well as conventions for the element names of the hierarchy. For example the \texttt{srcDirs} are relative to the \texttt{srcRoot}. Therefore \texttt{srcDirs} is a read-only property. If you want to change the name of the source dirs you need to do this via the \texttt{srcDirNames} property. But the paths you specify here are \emph{relative} to the \texttt{srcRoot}. This has the advantage to make bulk changes easy. If you change \texttt{srcRoot} from \texttt{src} to \texttt{source}, this automatically applies to all directory properties which are relative to \texttt{srcRoot}. As this also introduces an inflexibility, we have additional floating dirs, which are not bound to any hierarchy (see Table \ref{javaconventionFloatingDir}). For example code generation tool could make use of this, by adding a source dir which is located in the build folder. -\begin{table} +\noindent Here's the default directory layout assumed by the Java plugin: +\begin{table}[h!] \begin{center} \begin{tabular}{|l|l|} \hline \textbf{Folder} & \textbf{Meaning} \\ \hline @@ -18,7 +19,9 @@ \label{javalayout} \end{table} -\begin{table} + +\noindent The Java plugin creates several tasks automatically, all of which assume the default directory layout: +\begin{table}[h!] \begin{center} \begin{tabular}{|l|l|l|} \hline \textbf{Taskname} & \textbf{dependsOn} & \textbf{Type} \\ \hline @@ -40,31 +43,11 @@ \caption{Java Plugin Tasks} \label{javatasks} \end{table} +\clearpage -\begin{table} +\noindent The Java plugin provides properties for directories that aren't bound to any hierarchy: +\begin{table}[h!] \begin{center} - \begin{tabular}{|l|l|l|l|} \hline - \textbf{Dir Name} & \textbf{Dir File} & \textbf{Default Value Name} & \textbf{Default Value File}\\ \hline - srcRootName & srcRoot & \texttt{src} & \emph{projectDir}\texttt{/src}\\ \hline - srcDirNames & srcDirs & \texttt{main/java} & [\emph{srcRoot}\texttt{/main/java}] \\ \hline - resourceDirNames & resourceDirs & \texttt{main/resources} & [\emph{srcRoot}\texttt{/main/resources}]\\ \hline - testSrcDirNames & testSrcDirs & \texttt{test/java} & [\emph{srcRoot}\texttt{/test/java}] \\ \hline - testResourceDirNames & testResourceDirs & \texttt{main/resources} & [\emph{srcRoot}\texttt{/main/resources}] \\ \hline - srcDocsDirName & srcDocsDir & \texttt{docs} & \emph{srcRoot}\texttt{/docs} \\ \hline - classesDirName & classesDir & \texttt{classes} & \emph{buildDir}\texttt{/classes} \\ \hline - testClassesDirName & testClassesDir & \texttt{test-classes} & \emph{buildDir}\texttt{/test-classes} \\ \hline - testResultsDir & testResultsDirName & \texttt{test-results} & \emph{buildDir}\texttt{/test-results} \\ \hline - distsDirName & distsDir & \texttt{dists} & \emph{buildDir}\texttt{/dists} \\ \hline - docsDirName & docsDir & \texttt{docs} & \emph{buildDir}\texttt{/docs} \\ \hline - javadocDirName & javadocDir & \texttt{javadoc} & \emph{buildDir}\texttt{/javadoc} \\ \hline - \end{tabular} - \end{center} - \caption{Java Convention Object - Directory Hierarchy Properties} - \label{javaconventionDir} -\end{table} - -\begin{table} - \begin{center} \begin{tabular}{|l|l|l|} \hline \textbf{Property} & \textbf{Type} & \textbf{Default Value} \\ \hline floatingSrcDirs & List & empty \\ \hline @@ -77,7 +60,8 @@ \label{javaconventionFloatingDir} \end{table} -\begin{table} +\noindent The Java plugin also provides the project with properties to describe source code metadata: +\begin{table}[h!] \begin{center} \begin{tabular}{|l|l|l|} \hline \textbf{Property} & \textbf{Type} & \textbf{Default Value} \\ \hline @@ -87,10 +71,35 @@ metaInf & List & empty \\ \hline \end{tabular} \end{center} - \caption{Java Convention Object - Non Dir Properties} + \caption{Java Convention Object - Source Sode Metadata Properties} \label{javaconventionNonDir} \end{table} +\noindent The Java plugin's convention object creates several properties related to the directory hierarchy: +\begin{table}[h!] + \begin{center} + \begin{tabular}{|l|l|l|l|} \hline + \textbf{Dir Name} & \textbf{Dir File} & \textbf{Default Value Name} & \textbf{Default Value File}\\ \hline + srcRootName & srcRoot & \texttt{src} & \emph{projectDir}\texttt{/src}\\ \hline + srcDirNames & srcDirs & \texttt{main/java} & [\emph{srcRoot}\texttt{/main/java}] \\ \hline + resourceDirNames & resourceDirs & \texttt{main/resources} & [\emph{srcRoot}\texttt{/main/resources}]\\ \hline + testSrcDirNames & testSrcDirs & \texttt{test/java} & [\emph{srcRoot}\texttt{/test/java}] \\ \hline + testResourceDirNames & testResourceDirs & \texttt{main/resources} & [\emph{srcRoot}\texttt{/main/resources}] \\ \hline + srcDocsDirName & srcDocsDir & \texttt{docs} & \emph{srcRoot}\texttt{/docs} \\ \hline + classesDirName & classesDir & \texttt{classes} & \emph{buildDir}\texttt{/classes} \\ \hline + testClassesDirName & testClassesDir & \texttt{test-classes} & \emph{buildDir}\texttt{/test-classes} \\ \hline + testResultsDir & testResultsDirName & \texttt{test-results} & \emph{buildDir}\texttt{/test-results} \\ \hline + distsDirName & distsDir & \texttt{dists} & \emph{buildDir}\texttt{/dists} \\ \hline + docsDirName & docsDir & \texttt{docs} & \emph{buildDir}\texttt{/docs} \\ \hline + javadocDirName & javadocDir & \texttt{javadoc} & \emph{buildDir}\texttt{/javadoc} \\ \hline + \end{tabular} + \end{center} + \caption{Java Convention Object - Directory Hierarchy Properties} + \label{javaconventionDir} +\end{table} + +\noindent All other properies created by the Java plugin are specific to the various tasks it provides. + \section{Init} % (fold) \label{sec:initialization} The \texttt{init} task has no default action attached to it. It is meant to be a hook. You can add actions to it or associates your custom tasks with it. The Java Plugin executes this task before any other of its tasks get executed (except \texttt{clean} and \texttt{javadoc} which does not depends on \texttt{init}). @@ -98,7 +107,9 @@ \section{Javadoc} % (fold) \label{sec:javadoc} -The \texttt{javadoc} task has no default association with any other task. It has no prerequisites on the actions of other tasks, as it operates on the source. It does not provide a fine-grained configuration API yet. If you need this, you have to use for example Ant's javadoc task directly. +The \texttt{javadoc} Gradle task has no default association with any other task. It has no prerequisites on the actions of other tasks, as it operates on the source. It doesn't make every Javadoc feature available, but most of the common ones are supported. If you need to modify Jaavdoc parameters that aren't yet exposed by this task, you'll need to use Ant's Javadoc task directly (\texttt{ant.javadoc}). + +Here are the Java plugin convention properties that effect where data comes from and where generated files are placed: \begin{center} \begin{tabular}{|l|l|} \hline \multicolumn{2}{|c|}{Convention to Property Mapping} \\ \hline @@ -107,6 +118,69 @@ destinationDir & [javadocDir] \\ \hline \end{tabular} \end{center} +\clearpage + +\noindent The following properties effect how documents are created:\footnote{There's +no need to set these properties if you're willing to accept Javadoc's defaults.} +\begin{table}[h!] +\begin{center} + \begin{tabular}{|l|l|l|l|} \hline + \multicolumn{4}{|c|}{Javadoc Properties} \\ \hline + \textbf{Task Property} & \textbf{Convention Property} & \textbf{Type} & \textbf{Meaning} \\ \hline + access & javadocAccess & String & Highest privilege to generate docs for \\ \hline + additionalParam & javadocAdditionalParam & String & Free-form parameters \\ \hline + author & javadocAuthor & boolean & Flag whether to put author info in document \\ \hline + breakIterator & javadocBreakIterator & boolean & Use new breakiterator algorithm \\ \hline + classPath & javadocClassPath & List$<$String$>$ & User classpath (\textit{e.g.:} \texttt{["/x/y.jar"]}) \\ \hline + defaultExcludes & javadocDefaultExcludes & boolean & Use default excludes \\ \hline + doclet & javadocDoclet & String & Class name of custom doclet (\textit{e.g.:} \texttt{com.example.Xyz}) \\ \hline + docletPath & javadocDocletPath & List$<$String$>$ & Doclet classpath (\textit{e.g.:} \texttt{["/x/y.jar"]}) \\ \hline + encoding & javadocEncoding & String & I18N encoding used for generated docs \\ \hline + footer & javadocFooter & String & Footer text to put at bottom of each file \\ \hline + group & javadocGroup & String & Group specified packages together in overview page \\ \hline + header & javadocHeader & String & Header text to put at top of each file \\ \hline + helpFile & javadocHelpFile & File & The help file \\ \hline + link & javadocLink & String & Create links to javadoc output at the given URL \\ \hline + linkOffline & javadocLinkOffline & String & Link docs at space-delimited URLs \\ \hline + linkSource & javadocLinkSource & boolean & Generate hyperlinks in source file \\ \hline + locale & javadocLocale & String & Locale used for generated docs \\ \hline + maxMemory & javadocMaxMemory & String & Maximum amount of memory (\textit{e.g.:} \texttt{"128m"}) \\ \hline + overview & javadocOverview & File & Overview file to be included \\ \hline + splitIndex & javadocSplitIndex & boolean & Flag whether index should be split by letter \\ \hline + stylesheetFile & javadocStylesheetFile & File & CSS stylesheet for generated document \\ \hline + title & javadocTitle & String & Sets both the windowTitle and docTitle \\ \hline + useExternalFile & javadocUseExternalFile & boolean & Use temp. external file \\ \hline + use & javadocUse & boolean & Flag whether ``use" pages should be generated \\ \hline + verbose & javadocVerbose & boolean & Output messages about what Javadoc is doing \\ \hline + version & javadocVersion & boolean & Flag whether version tag should be included \\ \hline + \end{tabular} + \caption{Javadoc Task property types and meaning} + \label{javadocProperties} +\end{center} +\end{table} + +\noindent You can also call the \texttt{javadoc} task's +\texttt{include()} and \texttt{exclude()} functions; however, +the default settings are usually appropriate.\footnote{ + \texttt{include()} and \texttt{exclude()} \textit{augment} + the default file pattern lists, rather than \textit{replace} them.} +Here's a simple example of how to configure this task: + +\begin{Verbatim} + javadoc { + title = "A Dark And Stormy Night" // give all pages a compelling title + overview = new File("$srcRoot/overview.html") // make package use custom overview.html + access = "private" // create javadocs for 'private' stuff too + } +\end{Verbatim} + +\noindent For more information on Ant's \texttt{javadoc} task, see:\newline +\url{http://ant.apache.org/manual/CoreTasks/javadoc.html}\newline + +\noindent For more infomation on writing documentation for javadoc, see:\newline +\url{http://java.sun.com/j2se/javadoc/writingdoccomments/} + + % section javadoc (end) \section{Clean} % (fold) @@ -372,6 +446,6 @@ \end{tabular} \end{center} % subsection eclipse_project (end) -The java plugin also provides a task called \texttt{eclipse} which generates both of the eclipse tasks mentioned above. If you are using the war plugin, \texttt{eclipse} also leads to the execution of the \texttt{eclipseWtp} task. +The Java plugin also provides a task called \texttt{eclipse} which generates both of the eclipse tasks mentioned above. If you are using the war plugin, \texttt{eclipse} also leads to the execution of the \texttt{eclipseWtp} task. % section eclipse (end) % chapter the_java_plugin (end)