Author: vsiveton
Date: Sun Sep 13 12:53:32 2009
New Revision: 814309
URL: http://svn.apache.org/viewvc?rev=814309&view=rev
Log:
o reviewed and improved Javadoc and documentation by adding some examples (part
of MJAVADOC-258)
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.java
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocReport.java
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocUtil.java
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/TestJavadocReport.java
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate.apt.vm
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-doclet.apt.vm
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-javadoc-tool.apt.vm
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/exclude-package-names.apt.vm
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/group-configuration.apt.vm
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/javadoc-resources.apt.vm
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/links-configuration.apt.vm
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/selective-javadocs-report.apt.vm
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tag-configuration.apt.vm
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/taglet-configuration.apt.vm
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/test-javadocs.apt.vm
maven/plugins/trunk/maven-javadoc-plugin/src/site/fml/faq.fml
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.java?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.java
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.java
Sun Sep 13 12:53:32 2009
@@ -375,7 +375,8 @@
protected boolean aggregate;
/**
- * Set this to 'true' to debug Javadoc plugin. With this, 'options' and
'files' files are provided.
+ * Set this to <code>true</code> to debug the Javadoc plugin. With this,
<code>javadoc.bat(or.sh)</code>,
+ * <code>options</code>, <code>@packages</code> or <code>argfile</code>
files are provided in the output directory.
* <br/>
*
* @since 2.1
@@ -653,6 +654,11 @@
* <code>-subpackages</code>. Multiple packages can be separated by commas
(<code>,</code>), colons (<code>:</code>)
* or semicolons (<code>;</code>).
* <br/>
+ * Example:
+ * <pre>
+ *
<excludePackageNames>*.internal:org.acme.exclude1.*:org.acme.exclude2</excludePackageNames>
+ * </pre>
+ * <br/>
* See <a
href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#exclude";>exclude</a>.
* <br/>
* Since <a
href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/whatsnew-1.4.html#summary";>Java
1.4</a>.
@@ -932,17 +938,28 @@
* (<code>*</code>) meaning "match any characters". Multiple patterns can
be included in a group
* by separating them with colons (<code>:</code>).
* <br/>
- * See <a
href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#group";>group</a>.
- * <br/>
* Example:
* <pre>
* <groups>
* <group>
* <title>Core Packages</title>
- * <packages>org.apache.core</packages>
+ * <!-- To includes java.lang, java.lang.ref,
+ * java.lang.reflect and only java.util
+ * (i.e. not java.util.jar) -->
+ *
<packages>java.lang*:java.util</packages>
+ * </group>
+ * <group>
+ * <title>Extension Packages</title>
+ * <!-- To include javax.accessibility,
+ * javax.crypto, ... (among others) -->
+ * <packages>javax.*</packages>
* </group>
* </groups>
* </pre>
+ * <b>Note</b>: using <code>java.lang.*</code> for <code>packages</code>
would omit the <code>java.lang</code>
+ * package but using <code>java.lang*</code> will include it.
+ * <br/>
+ * See <a
href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#group";>group</a>.
* <br/>
* See <a
href="./apidocs/org/apache/maven/plugin/javadoc/options/Group.html">Javadoc</a>.
* <br/>
@@ -1026,21 +1043,21 @@
/**
* Creates links to existing javadoc-generated documentation of external
referenced classes.
* <br/>
- * <b>Note 1</b>: only used is {...@link #isOffline} is set to
<code>false</code>.
- * <br/>
- * <b>Note 2</b>: all given links should have a fetchable
<code>/package-list</code> file. For instance:
+ * <b>Notes</b>:
+ * <ol>
+ * <li>only used is {...@link #isOffline} is set to
<code>false</code>.</li>
+ * <li>all given links should have a fetchable <code>/package-list</code>
file. For instance:
* <pre>
* <links>
- * <link>http://java.sun.com/j2se/1.4.2/docs/api</link>
+ *
<link>http://java.sun.com/j2se/1.4.2/docs/api</link>
* <links>
* </pre>
- * will be used because
<code>http://java.sun.com/j2se/1.4.2/docs/api/package-list</code> exists.
- * <br/>
- * <b>Note 1</b>: if {...@link #detectLinks} is defined, the links between
the project dependencies are
- * automatically added.
- * <b>Note 2</b>: if {...@link #detectJavaApiLink} is defined, a Java API
link, based on the Java verion of the
- * project's sources, will be added automatically.
- * <br/>
+ * will be used because
<code>http://java.sun.com/j2se/1.4.2/docs/api/package-list</code> exists.</li>
+ * <li>if {...@link #detectLinks} is defined, the links between the
project dependencies are
+ * automatically added.</li>
+ * <li>if {...@link #detectJavaApiLink} is defined, a Java API link, based
on the Java verion of the
+ * project's sources, will be added automatically.</li>
+ * </ol>
* See <a
href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#link";>link</a>.
*
* @parameter expression="${links}"
@@ -1465,7 +1482,17 @@
* </tag>
* </tags>
* </pre>
- * <br/>
+ * <b>Note</b>: the placement should be a combinaison of Xaoptcmf letters:
+ * <ul>
+ * <li><b><code>X</code></b> (disable tag)</li>
+ * <li><b><code>a</code></b> (all)</li>
+ * <li><b><code>o</code></b> (overview)</li>
+ * <li><b><code>p</code></b> (packages)</li>
+ * <li><b><code>t</code></b> (types, that is classes and interfaces)</li>
+ * <li><b><code>c</code></b> (constructors)</li>
+ * <li><b><code>m</code></b> (methods)</li>
+ * <li><b><code>f</code></b> (fields)</li>
+ * </ul>
* See <a
href="./apidocs/org/apache/maven/plugin/javadoc/options/Tag.html">Javadoc</a>.
* <br/>
*
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocReport.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocReport.java?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocReport.java
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocReport.java
Sun Sep 13 12:53:32 2009
@@ -72,7 +72,8 @@
private String destDir;
/**
- * The name of the Javadoc report.
+ * The name of the Javadoc report to be displayed in the Maven Generated
Reports page
+ * (i.e. <code>project-reports.html</code>).
*
* @since 2.1
* @parameter expression="${name}"
@@ -80,7 +81,8 @@
private String name;
/**
- * The description of the Javadoc report.
+ * The description of the Javadoc report to be displayed in the Maven
Generated Reports page
+ * (i.e. <code>project-reports.html</code>).
*
* @since 2.1
* @parameter expression="${description}"
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocUtil.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocUtil.java?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocUtil.java
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocUtil.java
Sun Sep 13 12:53:32 2009
@@ -803,7 +803,7 @@
* Validate if a charset is supported on this platform.
*
* @param charsetName the charsetName to be check.
- * @return <code>true</code> if the charset is supported by the JVM,
<code>false</code> otherwise.
+ * @return <code>true</code> if the given charset is supported by the JVM,
<code>false</code> otherwise.
*/
protected static boolean validateEncoding( String charsetName )
{
@@ -826,6 +826,7 @@
{
IOUtil.close( osw );
}
+
return true;
}
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/TestJavadocReport.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/TestJavadocReport.java?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/TestJavadocReport.java
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/TestJavadocReport.java
Sun Sep 13 12:53:32 2009
@@ -68,6 +68,8 @@
* Specifies that Javadoc should retrieve the text for the Test overview
documentation from the "source" file
* specified by path/filename and place it on the Overview page
(overview-summary.html).
* <br/>
+ * <b>Note</b>: could be in conflict with <nooverview/>.
+ * <br/>
* See <a
href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#overview";>overview</a>.
* <br/>
*
@@ -111,6 +113,10 @@
/**
* Specifies the Test Javadoc resources directory to be included in the
Javadoc (i.e. package.html, images...).
+ * <br/>
+ * Could be used in addition of <code>docfilessubdirs</code> parameter.
+ * <br/>
+ * See <a href="#docfilessubdirs">docfilessubdirs</a>.
*
* @parameter expression="${basedir}/src/test/javadoc"
alias="javadocDirectory"
* @since 2.5
@@ -122,7 +128,8 @@
// ----------------------------------------------------------------------
/**
- * The name of the Test Javadoc report.
+ * The name of the Test Javadoc report to be displayed in the Maven
Generated Reports page
+ * (i.e. <code>project-reports.html</code>).
*
* @parameter expression="${testName}" alias="name"
* @since 2.5
@@ -130,7 +137,8 @@
private String testName;
/**
- * The description of the Test Javadoc report.
+ * The description of the Test Javadoc report to be displayed in the Maven
Generated Reports page
+ * (i.e. <code>project-reports.html</code>).
*
* @parameter expression="${testDescription}" alias="description"
* @since 2.5
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate.apt.vm?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate.apt.vm
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate.apt.vm
Sun Sep 13 12:53:32 2009
@@ -85,8 +85,44 @@
The {{{../javadoc-mojo.html#aggregate}\<aggregate/\>}} parameter doesn't
include generate source directories defined
using the
{{{http://mojo.codehaus.org/build-helper-maven-plugin/add-source-mojo.html}build-helper:add-source}}.
In
- this case, you need to use the <<<aggregate>>> goal and <<<test-aggregate>>>
goals. You could also define several
- \<reportSet/\> like the following:
+ this case, you need to use the <<<aggregate>>> goal and <<<test-aggregate>>>
goals. You could define these goals in the
+ \<build/\> element (using the \<execution/\> tag) or \<reporting/\> element
(using the \<reportSet/\> tag) as shown
+ below. For more information, refer to the
{{{./selective-javadocs-report.html}Selective Javadocs Reports page}}.
+
++-----+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <!-- Default configuration for all reports -->
+ ...
+ </configuration>
+ <executions>
+ <execution>
+ <id>aggregate</id>
+ <goals>
+ <goal>aggregate</goal>
+ </goals>
+ <phase>site</phase>
+ <configuration>
+ <!-- Specific configuration for the aggregate report -->
+ ...
+ </configuration>
+ </execution>
+ ...
+ </executions>
+ </plugin>
+ ...
+ </plugins>
+ </build>
+ ...
+</project>
++-----+
+-----+
@@ -98,10 +134,15 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>${project.version}</version>
+ <configuration>
+ <!-- Default configuration for all reports -->
+ ...
+ </configuration>
<reportSets>
<reportSet>
<id>non-aggregate</id>
<configuration>
+ <!-- Specific configuration for the non aggregate report -->
...
</configuration>
<reports>
@@ -111,14 +152,17 @@
<reportSet>
<id>aggregate</id>
<configuration>
+ <!-- Specific configuration for the aggregate report -->
...
</configuration>
<reports>
<report>aggregate</report>
</reports>
</reportSet>
+ ...
</reportSets>
</plugin>
+ ...
</plugins>
</reporting>
...
@@ -137,4 +181,3 @@
* {{{../test-aggregate-jar-mojo.html}javadoc:test-aggregate-jar}} to create
an archive file of the test Javadoc files.
[]
-
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-doclet.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-doclet.apt.vm?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-doclet.apt.vm
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-doclet.apt.vm
Sun Sep 13 12:53:32 2009
@@ -39,42 +39,44 @@
+-----+
<project>
- ...
- <reporting> (or <build>)
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-javadoc-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>
-
- <!-- <docletPath>/path/to/UmlGraph.jar</docletPath> -->
- <docletArtifact>
- <groupId>org.umlgraph</groupId>
- <artifactId>doclet</artifactId>
- <version>5.1</version>
- </docletArtifact>
- <additionalparam>-views</additionalparam>
- <useStandardDocletOptions>true</useStandardDocletOptions>
- </configuration>
- </plugin>
- ...
- </plugins>
- </reporting> (or </build>)
- ...
+ ...
+ <reporting> (or <build>)
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>
+
+ <!-- <docletPath>/path/to/UmlGraph.jar</docletPath> -->
+ <docletArtifact>
+ <groupId>org.umlgraph</groupId>
+ <artifactId>doclet</artifactId>
+ <version>5.1</version>
+ </docletArtifact>
+ <additionalparam>-views</additionalparam>
+ <useStandardDocletOptions>true</useStandardDocletOptions>
+ </configuration>
+ </plugin>
+ ...
+ </plugins>
+ </reporting> (or </build>)
+ ...
</project>
+-----+
<<Note>>:
- * {{{../javadoc-mojo.html#additionalparam}\<additionalparam/\>}} is used to
set additional parameters on the command
- line, specifically for doclet options.
+ * {{{../javadoc-mojo.html#additionalparam}\<additionalparam/\>}} parameter
could be used to set additional
+ parameters on the command line, specifically for doclet options.
- *
{{{../javadoc-mojo.html#useStandardDocletOptions}\<useStandardDocletOptions/\>}}
uses the
+ *
{{{../javadoc-mojo.html#useStandardDocletOptions}\<useStandardDocletOptions/\>}}
parameter could be used to specify
+ that the given doclet should use the
{{{http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#standard}options
provided by the Standard Doclet}}.
- * If you need more artifacts in the docletpath, you could use
{{{../javadoc-mojo.html#docletArtifacts}\<docletArtifacts/\>}}.
+ * If you need more artifacts in the docletpath, you could use the
+ {{{../javadoc-mojo.html#docletArtifacts}\<docletArtifacts/\>}} parameter.
[]
@@ -92,51 +94,51 @@
+-----+
<project>
- ...
- <reporting>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-javadoc-plugin</artifactId>
- <version>${project.version}</version>
- <reportSets>
- <reportSet>
- <id>html</id>
- <reports>
- <report>javadoc</report>
- </reports>
- </reportSet>
- <reportSet>
- <id>doccheck</id>
- <configuration>
- <doclet>com.sun.tools.doclets.doccheck.DocCheck</doclet>
-
- <!-- <docletPath>/path/to/doccheck.jar</docletPath> -->
- <docletArtifact>
- <groupId>com.sun.tools.doclets</groupId>
- <artifactId>doccheck</artifactId>
- <version>1.2b2</version>
- </docletArtifact>
- <additionalparam>
+ ...
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>${project.version}</version>
+ <reportSets>
+ <reportSet>
+ <id>html</id>
+ <reports>
+ <report>javadoc</report>
+ </reports>
+ </reportSet>
+ <reportSet>
+ <id>doccheck</id>
+ <configuration>
+ <doclet>com.sun.tools.doclets.doccheck.DocCheck</doclet>
+
+ <!-- <docletPath>/path/to/doccheck.jar</docletPath> -->
+ <docletArtifact>
+ <groupId>com.sun.tools.doclets</groupId>
+ <artifactId>doccheck</artifactId>
+ <version>1.2b2</version>
+ </docletArtifact>
+ <additionalparam>
-d \${project.build.directory}/site/doccheck
- </additionalparam>
+ </additionalparam>
- <!-- Other dir than apidocs -->
- <destDir>doccheck</destDir>
+ <!-- Other dir than apidocs -->
+ <destDir>doccheck</destDir>
- <!-- For the project-reports page-->
- <name>DocCheck</name>
- <description>DocCheck documentation.</description>
- </configuration>
- <reports>
- <report>javadoc</report>
- </reports>
- </reportSet>
- </reportSets>
- </plugin>
- ...
- </plugins>
- </reporting>
- ...
+ <!-- For the project-reports page-->
+ <name>DocCheck</name>
+ <description>DocCheck documentation.</description>
+ </configuration>
+ <reports>
+ <report>javadoc</report>
+ </reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
+ ...
+ </plugins>
+ </reporting>
+ ...
</project>
+-----+
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-javadoc-tool.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-javadoc-tool.apt.vm?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-javadoc-tool.apt.vm
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-javadoc-tool.apt.vm
Sun Sep 13 12:53:32 2009
@@ -38,25 +38,30 @@
+-----+
<project>
- ...
- <reporting> (or <build>)
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-javadoc-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
-
<javadocExecutable>C:\jdk1.6.0\bin\javadoc.exe</javadocExecutable>
- ...
- </configuration>
- </plugin>
- ...
- </plugins>
- </reporting> (or </build>)
- ...
+ ...
+ <reporting> (or <build>)
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <javadocExecutable>C:\jdk1.6.0\bin\javadoc.exe</javadocExecutable>
+ ...
+ </configuration>
+ </plugin>
+ ...
+ </plugins>
+ </reporting> (or </build>)
+ ...
</project>
+-----+
+ <<IMPORTANT NOTE>>: by using
{{{../javadoc-mojo.html#javadocExecutable}\<javadocExecutable/\>}} parameter,
the build
+ will be plateform dependent! A good practice is to define an environnement
variable (i.e. JAVA_1.6_HOME), so you
+ could specify it: (i.e.
\<javadocExecutable\>\u0024\{env.JAVA_1.6_HOME\}/bin/javadoc\</javadocExecutable\>).
An other
+ ways is to define a POM property using
\<project\>\<properties/\>\</project\>.
+
* Using Alternate Javadoc Version
In the same way, the Maven Javadoc Plugin tries to auto-detect the Javadoc
Tool version by calling
@@ -66,22 +71,22 @@
+-----+
<project>
- ...
- <reporting> (or <build>)
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-javadoc-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <javadocVersion>1.5</javadocVersion>
- ...
- </configuration>
- </plugin>
- ...
- </plugins>
- </reporting> (or </build>)
- ...
+ ...
+ <reporting> (or <build>)
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <javadocVersion>1.5</javadocVersion>
+ ...
+ </configuration>
+ </plugin>
+ ...
+ </plugins>
+ </reporting> (or </build>)
+ ...
</project>
+-----+
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/exclude-package-names.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/exclude-package-names.apt.vm?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/exclude-package-names.apt.vm
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/exclude-package-names.apt.vm
Sun Sep 13 12:53:32 2009
@@ -3,7 +3,7 @@
------
Maria Odea Ching
------
- 2009-09-11
+ 2009-09-12
------
~~ Licensed to the Apache Software Foundation (ASF) under one
@@ -28,29 +28,73 @@
Excluding Packages
- To exclude specific packages from the Javadoc tool, use
{{{../javadoc-mojo.html#excludePackageNames}\<excludePackageNames/\>}}
+ To exclude specific packages, use
{{{../javadoc-mojo.html#excludePackageNames}\<excludePackageNames/\>}} parameter
as shown below. The parameter accepts wildcard (*) characters in its value
but the wildcards should either be at the
start or the end of the package name. If more than one package is to be
excluded, each package name must be separated
- either with a colon (':'), a comma (',') or a semicolon (';').
+ either with a colon (':'), a comma (',') or a semicolon (';'). (similar to the
+
{{{http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#exclude}Javadoc
Tool}})
+
+ For instance, with the following packages:
+
++-----+
+com.mycompany.myapp
+com.mycompany.myapp.package1
+com.mycompany.myapp.package1.subpackage1
+com.mycompany.myapp.package1.subpackage2
+com.mycompany.myapp.package1.subpackage3
+com.mycompany.myapp.package1.util
+com.mycompany.myapp.package2
+com.mycompany.myapp.package2.subpackage4
+com.mycompany.myapp.package2.subpackage5
+com.mycompany.myapp.package2.util
+com.mycompany.myapp.package3
+com.mycompany.myapp.package3.subpackage6
+com.mycompany.myapp.package3.subpackage6.subsubpackage1
+com.mycompany.myapp.package3.subpackage6.subsubpackage2
+com.mycompany.myapp.package3.subpackage7
+com.mycompany.myapp.package3.util
++-----+
+
+ You could have the following configuration:
+-----+
<project>
...
- <reporting>
+ <reporting> (or <build>)
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>${project.version}</version>
<configuration>
- ...
-
<excludePackageNames>*.internal:org.acme.exclude1.*:org.acme.exclude2</excludePackageNames>
+ <!--
+ Exclude packages:
+ com.mycompany.myapp.package1.subpackage1
+ com.mycompany.myapp.package1.subpackage2
+ com.mycompany.myapp.package1.subpackage3
+ com.mycompany.myapp.package1.util
+ com.mycompany.myapp.package2
+ com.mycompany.myapp.package2.subpackage4
+ com.mycompany.myapp.package2.subpackage5
+ com.mycompany.myapp.package2.util
+ com.mycompany.myapp.package3.util
+ BUT include the packages:
+ com.mycompany.myapp
+ com.mycompany.myapp.package1
+ com.mycompany.myapp.package3
+ com.mycompany.myapp.package3.subpackage6
+ com.mycompany.myapp.package3.subpackage6.subsubpackage1
+ com.mycompany.myapp.package3.subpackage6.subsubpackage2
+ com.mycompany.myapp.package3.subpackage7
+ -->
+
<excludePackageNames>com.mycompany.myapp.package1.*:com.mycompany.myapp.package2:*.util.*</excludePackageNames>
...
</configuration>
</plugin>
+ ...
</plugins>
...
- </reporting>
+ </reporting> (or <build>)
...
</project>
+-----+
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/group-configuration.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/group-configuration.apt.vm?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/group-configuration.apt.vm
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/group-configuration.apt.vm
Sun Sep 13 12:53:32 2009
@@ -4,7 +4,7 @@
Vincent Siveton
Maria Odea Ching
------
- 2009-08-04
+ 2009-09-12
------
~~ Licensed to the Apache Software Foundation (ASF) under one
@@ -29,7 +29,28 @@
Grouping Packages
- To set a grouping for different packages, use the
{{{../javadoc-mojo.html#groups}\<groups/\>}} configuration in your pom:
+ To set a grouping for different packages, use the
{{{../javadoc-mojo.html#groups}\<groups/\>}} parameter as shown
+ below. Each group will be consist of a \<title/\> and a \<packages/\> (as
String). The \<packages/\> element supports
+ wildcard (*) to allow subpackages. If more than one package is to be
included, each package name must be separated
+ colon (:) separated (similar to the
+
{{{http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#group}Javadoc
Tool}}).
+
+ For instance, with the following packages:
+
++-----+
+com.mycompany.myapp
+com.mycompany.myapp.package1
+com.mycompany.myapp.package1.subpackage1
+com.mycompany.myapp.package1.subpackage2
+com.mycompany.myapp.package1.subpackage3
+com.mycompany.myapp.package1.util
+com.mycompany.myapp.package2
+com.mycompany.myapp.package2.subpackage4
+com.mycompany.myapp.package2.subpackage5
+com.mycompany.myapp.package2.util
++-----+
+
+ You could have the following configuration:
+-----+
<project>
@@ -41,20 +62,89 @@
<artifactId>maven-javadoc-plugin</artifactId>
<version>${project.version}</version>
<configuration>
- ...
<groups>
<group>
- <title>Core Packages</title>
- <packages>org.apache.maven.plugin.javadoc.test1</packages>
+ <title>Example 1 - Group Packages</title>
+ <!--
+ Include packages:
+ com.mycompany.myapp
+ com.mycompany.myapp.package1
+ BUT exclude all subpackages
+ -->
+
<packages>com.mycompany.myapp:com.mycompany.myapp.package1</packages>
+ </group>
+ <group>
+ <title>Example 2 - Group Packages</title>
+ <!--
+ Include packages:
+ com.mycompany.myapp.package1.subpackage1
+ com.mycompany.myapp.package1.subpackage2
+ com.mycompany.myapp.package1.subpackage3
+ com.mycompany.myapp.package1.util
+ BUT exclude the root package:
+ com.mycompany.myapp.package1
+ -->
+ <packages>com.mycompany.myapp.package1.*</packages>
+ </group>
+ <group>
+ <title>Example 3 - Group Packages</title>
+ <!--
+ Include packages:
+ com.mycompany.myapp.package1
+ com.mycompany.myapp.package1.subpackage1
+ com.mycompany.myapp.package1.subpackage2
+ com.mycompany.myapp.package1.subpackage3
+ com.mycompany.myapp.package1.util
+ -->
+ <packages>com.mycompany.myapp.package1*</packages>
+ </group>
+ <group>
+ <title>Example 4 - Group Packages</title>
+ <!--
+ Include packages:
+ com.mycompany.myapp.package1
+ com.mycompany.myapp.package1.subpackage1
+ com.mycompany.myapp.package1.subpackage2
+ com.mycompany.myapp.package1.subpackage3
+ com.mycompany.myapp.package1.util
+ com.mycompany.myapp.package2
+ com.mycompany.myapp.package2.subpackage4
+ com.mycompany.myapp.package2.subpackage5
+ com.mycompany.myapp.package2.util
+ -->
+ <packages>com.mycompany.myapp.package*</packages>
+ </group>
+ <group>
+ <title>Example 5 - Group Packages</title>
+ <!--
+ Include packages:
+ com.mycompany.myapp.package1.subpackage1
+ com.mycompany.myapp.package1.subpackage2
+ com.mycompany.myapp.package1.subpackage3
+ com.mycompany.myapp.package1.util
+ com.mycompany.myapp.package2.subpackage4
+ com.mycompany.myapp.package2.subpackage5
+ com.mycompany.myapp.package2.util
+ BUT exclude the root packages:
+ com.mycompany.myapp.package1
+ com.mycompany.myapp.package2
+ -->
+
<packages>com.mycompany.myapp.package1.*:com.mycompany.myapp.package2.*</packages>
</group>
<group>
- <title>Extension Packages</title>
- <packages>org.apache.maven.plugin.javadoc.test2</packages>
+ <title>Example 6 - Group Packages</title>
+ <!--
+ Include nothing.
+ The packages com.mycompany.myapp.package1.util and
com.mycompany.myapp.package2.util
+ will be in "Other Packages" group
+ -->
+ <packages>*.util.*</packages>
</group>
</groups>
...
</configuration>
</plugin>
+ ...
</plugins>
...
</reporting> (or </build>)
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/javadoc-resources.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/javadoc-resources.apt.vm?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/javadoc-resources.apt.vm
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/javadoc-resources.apt.vm
Sun Sep 13 12:53:32 2009
@@ -28,7 +28,7 @@
Using Javadoc Resources
- The {{{../javadoc-mojo.html#javadocDirectory}\<javadocDirectory/\>}}/\>
parameter can be used to include Javadoc
+ The {{{../javadoc-mojo.html#javadocDirectory}\<javadocDirectory/\>}}
parameter can be used to include Javadoc
resources like HTML or images. By default, all javadoc resources are in
<$\{basedir\}/src/main/javadoc> directory.
Here is a typical set of resources files used by the Maven Javadoc plugin:
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/links-configuration.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/links-configuration.apt.vm?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/links-configuration.apt.vm
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/links-configuration.apt.vm
Sun Sep 13 12:53:32 2009
@@ -28,7 +28,8 @@
Configuring <<<links>>> Parameter
- You could add cross reference links to external projects using the
{{{../javadoc-mojo.html#links}\<links/\>}}
+~~ Using anchor links produces a Velocity error.
+ You could add cross reference links to external projects using the
{{{../javadoc-mojo.html}\<links/\>}}
parameters. For instance:
+-----+
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/selective-javadocs-report.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/selective-javadocs-report.apt.vm?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/selective-javadocs-report.apt.vm
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/selective-javadocs-report.apt.vm
Sun Sep 13 12:53:32 2009
@@ -3,7 +3,7 @@
------
Vincent Siveton
------
- 2009-08-04
+ 2009-09-13
------
~~ Licensed to the Apache Software Foundation (ASF) under one
@@ -29,7 +29,48 @@
Selective Javadocs Reports
To run the Javadocs reports selectively, you need to include only the
Javadocs reports that you prefer.
- Use <<<mvn site>>> to generate the selected reports.
+ As said in the
{{{../faq.html#Where_in_the_pom.xml_do_I_configure_the_Javadoc_Plugin}FAQ}},
the configuration
+ depends on the \<build/\> tag or \<reporting/\> tag used.
+
+* Using \<build/\> Tag
+
++-----+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <!-- Default configuration for all reports -->
+ ...
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>javadoc</goal>
+ <goal>test-javadoc</goal>
+ </goals>
+ <phase>site</phase>
+ <configuration>
+ <!-- Specific configuration for the given reports -->
+ ...
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-----+
+
+ Since the phase is <<<site>>>, you need to call <<<mvn site>>> to generate
the selected reports (only main and test
+ javadocs).
+
+* Using \<reporting/\> Tag
+-----+
@@ -47,13 +88,24 @@
</configuration>
<reportSets>
<reportSet>
+ <id>default</id>
+ <configuration>
+ <!-- Specific configuration for the given reports -->
+ ...
+ </configuration>
<reports>
<report>javadoc</report>
- <!-- <report>test-javadoc</report> -->
- <configuration>
- <!-- Specific configuration for the given report -->
- ...
- </configuration>
+ <report>test-javadoc</report>
+ </reports>
+ </reportSet>
+ <reportSet>
+ <id>aggregate</id>
+ <configuration>
+ <!-- Specific configuration for the given reports -->
+ ...
+ </configuration>
+ <reports>
+ <report>aggregate</report>
</reports>
</reportSet>
</reportSets>
@@ -63,3 +115,5 @@
...
</project>
+-----+
+
+ Just call <<<mvn site>>> to generate the selected reports (main, test and
aggregate javadocs).
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tag-configuration.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tag-configuration.apt.vm?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tag-configuration.apt.vm
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tag-configuration.apt.vm
Sun Sep 13 12:53:32 2009
@@ -4,7 +4,7 @@
Vincent Siveton
Maria Odea Ching
------
- 2009-08-04
+ 2009-09-12
------
~~ Licensed to the Apache Software Foundation (ASF) under one
@@ -29,7 +29,29 @@
Configuring Custom Javadoc Tags
- You can configure any custom tags used in your javadoc via the
{{{../javadoc-mojo.html#tags}\<tags/\>}} element:
+ To configure any custom tags, use {{{../javadoc-mojo.html#tags}\<tags/\>}}
parameter as shown below. Each tag will
+ be consist of a \<name/\>, a \<placement/\> and a \<head/\>. The
\<placement/\> should be a combination of the
+ letters Xaoptcmf:
+
+ * X (disable tag)
+
+ * a (all)
+
+ * o (overview)
+
+ * p (packages)
+
+ * t (types, that is classes and interfaces)
+
+ * c (constructors)
+
+ * m (methods)
+
+ * f (fields)
+
+ []
+
+ For instance, with the following configuration:
+-----+
<project>
@@ -45,7 +67,7 @@
<tags>
<tag>
<name>todo</name>
- <!-- Should be a combination of the letters Xaoptcmf -->
+ <!-- todo tag for all places -->
<placement>a</placement>
<head>To do something:</head>
</tag>
@@ -59,3 +81,26 @@
...
</project>
+-----+
+
+ and with the following todo tag in a class:
+
++-----+
+/**
+ * Hello world!
+ *
+ * @todo complete me!
+ */
+public class App {}
++-----+
+
+ the Javadoc tool will generate the following Javadoc:
+
++-----+
+public class App
+extends Object
+
+Hello world!
+
+To do something:
+ complete me!
++-----+
\ No newline at end of file
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/taglet-configuration.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/taglet-configuration.apt.vm?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/taglet-configuration.apt.vm
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/taglet-configuration.apt.vm
Sun Sep 13 12:53:32 2009
@@ -28,8 +28,9 @@
Configuring Custom Taglets
- You could configure any custom taglets in your Javadoc Plugin configuration
via the \<taglet/\>, \<taglets/\>
- or \<tagletArtifacts/\> parameters, depending the number of taglets used.
+ You could configure any custom taglets in your Javadoc Plugin configuration
via the
+ {{{../javadoc-mojo.html#taglet}\<taglet/\>}},
{{{../javadoc-mojo.html#taglets}\<taglets/\>}}, or
+ {{{../javadoc-mojo.html#tagletArtifacts}\<tagletArtifacts/\>}} parameters,
depending the number of taglets used.
For more information about the taglet technology, please refer to
{{http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/taglet/overview.html}}.
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/test-javadocs.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/test-javadocs.apt.vm?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/test-javadocs.apt.vm
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/test-javadocs.apt.vm
Sun Sep 13 12:53:32 2009
@@ -28,14 +28,6 @@
Generating Test Javadocs
- There are two ways to generate the test javadocs in the Maven Javadoc plugin:
-
- * using the javadoc:test-javadoc goal
-
- * using the \<reportSets/\> configuration parameter
-
- []
-
Here is a typical project used by the Maven Javadoc plugin:
+-----+
Modified: maven/plugins/trunk/maven-javadoc-plugin/src/site/fml/faq.fml
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/fml/faq.fml?rev=814309&r1=814308&r2=814309&view=diff
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/site/fml/faq.fml (original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/site/fml/faq.fml Sun Sep 13
12:53:32 2009
@@ -50,7 +50,9 @@
</p>
<p>
<b>IMPORTANT NOTE</b>: using <i><reporting/></i> or
<i><build/></i> elements have not the same
- behavior, refer to <a href="./usage.html">usage page</a> for more
information.
+ behavior, refer to
+ <a
href="http://maven.apache.org/guides/mini/guide-configuring-plugins.html#Using_the_reporting_Tag_VS_build_Tag";>Using
the <reporting/> Tag VS <build/> Tag</a>
+ part for more information.
</p>
</answer>
</faq>
