Author: oching Date: Thu Jun 22 01:30:38 2006 New Revision: 416295 URL: http://svn.apache.org/viewvc?rev=416295&view=rev Log: PR: MJAVADOC-79
Reviewed and revised plugin documentation. Added: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate.apt maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternateDoclet.apt maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/excludePackageNames.apt maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/groupConfiguration.apt maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/stylesheetConfiguration.apt maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tagConfiguration.apt maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/faq.apt maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/overview.apt maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt Removed: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/configuration.apt maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/introduction.apt Modified: maven/plugins/trunk/maven-javadoc-plugin/pom.xml 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/JavadocJar.java maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocReport.java maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml Modified: maven/plugins/trunk/maven-javadoc-plugin/pom.xml URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/pom.xml?rev=416295&r1=416294&r2=416295&view=diff ============================================================================== --- maven/plugins/trunk/maven-javadoc-plugin/pom.xml (original) +++ maven/plugins/trunk/maven-javadoc-plugin/pom.xml Thu Jun 22 01:30:38 2006 @@ -9,7 +9,52 @@ <artifactId>maven-javadoc-plugin</artifactId> <packaging>maven-plugin</packaging> <name>Maven Javadoc Plugin</name> + <description> + The Maven Javadoc Plugin is a plugin that uses the javadoc tool for generating javadocs for + the specified project. + </description> <version>2.1-SNAPSHOT</version> + <url>http://maven.apache.org/plugins/maven-javadoc-plugin</url> + <issueManagement> + <system>jira</system> + <url>http://jira.codehaus.org/browse/MJAVADOC</url> + </issueManagement> + <inceptionYear>2004</inceptionYear> + <mailingLists> + <mailingList> + <name>Maven User List</name> + <subscribe>[EMAIL PROTECTED]</subscribe> + <unsubscribe>[EMAIL PROTECTED]</unsubscribe> + <post>users@maven.apache.org</post> + <archive>http://mail-archives.apache.org/mod_mbox/maven-users</archive> + <otherArchives> + <otherArchive>http://www.mail-archive.com/users@maven.apache.org/</otherArchive> + <otherArchive>http://www.nabble.com/Maven---Users-f178.html</otherArchive> + </otherArchives> + </mailingList> + <mailingList> + <name>Maven Developer List</name> + <subscribe>[EMAIL PROTECTED]</subscribe> + <unsubscribe>[EMAIL PROTECTED]</unsubscribe> + <post>dev@maven.apache.org</post> + <archive>http://mail-archives.apache.org/mod_mbox/maven-dev</archive> + </mailingList> + <mailingList> + <name>Maven Commits List</name> + <subscribe>[EMAIL PROTECTED]</subscribe> + <unsubscribe>[EMAIL PROTECTED]</unsubscribe> + <post>commits@maven.apache.org</post> + <archive>http://mail-archives.apache.org/mod_mbox/maven-dev</archive> + </mailingList> + </mailingLists> + <scm> + <connection>scm:svn:http://svn.apache.org/repos/asf/maven/plugins/trunk/maven-javadoc-plugin</connection> + <developerConnection>scm:svn:https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-javadoc-plugin</developerConnection> + <url>http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin</url> + </scm> + <prerequisites> + <maven>2.0</maven> + </prerequisites> <build> <plugins> <plugin> @@ -67,4 +112,17 @@ <version>1.0-beta-1</version> </dependency> </dependencies> + <reporting> + <plugins> + <plugin> + <artifactId>maven-javadoc-plugin</artifactId> + </plugin> + <plugin> + <artifactId>maven-jxr-plugin</artifactId> + </plugin> + <plugin> + <artifactId>maven-changelog-plugin</artifactId> + </plugin> + </plugins> + </reporting> </project> 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=416295&r1=416294&r2=416295&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 Thu Jun 22 01:30:38 2006 @@ -562,21 +562,29 @@ private String windowtitle; /** + * Used for resolving artifacts + * * @component */ private ArtifactResolver resolver; /** + * Factory for creating artifact objects + * * @component */ private ArtifactFactory factory; /** + * The local repository where the artifacts are located + * * @parameter expression="${localRepository}" */ private ArtifactRepository localRepository; /** + * The remote repositories where artifacts are located + * * @parameter expression="${project.remoteArtifactRepositories}" */ private List remoteRepositories; Modified: maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocJar.java URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocJar.java?rev=416295&r1=416294&r2=416295&view=diff ============================================================================== --- maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocJar.java (original) +++ maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocJar.java Thu Jun 22 01:30:38 2006 @@ -61,6 +61,8 @@ private String finalName; /** + * Used for attaching the artifact in the project + * * @component */ private MavenProjectHelper projectHelper; 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=416295&r1=416294&r2=416295&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 Thu Jun 22 01:30:38 2006 @@ -52,6 +52,8 @@ // ---------------------------------------------------------------------- /** + * Generates the site report + * * @component */ private Renderer siteRenderer; Added: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate.apt URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate.apt?rev=416295&view=auto ============================================================================== --- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate.apt (added) +++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate.apt Thu Jun 22 01:30:38 2006 @@ -0,0 +1,49 @@ + ------ + Using Aggregate + ------ + Maria Odea Ching + ------ + 20 June 2006 + ------ + + +Using Aggregate + + The aggregate parameter can be used to generate javadocs for multi-module projects. It gives the option to + generate 1 javadoc report for the whole project (all modules) or generate 1 javadoc report for each module. + + For example, you have the following directory structure: + +-------------------- ++-Project + +-Module1 + +-Module2 + +-Module3 +-------------------- + + When you execute javadoc from Project directory with aggregate set to "true", a javadoc report will be created + in the target directory of Project wherein all the javadocs of Project's modules are included. If aggregate is + set to false, a javadoc report for Module1 will be generated in the target directory of Module1, a javadoc + report for Module2 will be generated in the target directory of Module2, and a javadoc report for Module3 will be + generated in the target directory of Module3. + +------------------- +<project> + ... + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <configuration> + ... + <aggregate>true</aggregate> + ... + </configuration> + </plugin> + </plugins> + ... + </build> + ... +</project> +------------------- Added: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternateDoclet.apt URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternateDoclet.apt?rev=416295&view=auto ============================================================================== --- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternateDoclet.apt (added) +++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternateDoclet.apt Thu Jun 22 01:30:38 2006 @@ -0,0 +1,57 @@ + ------ + Using Alternate Doclet + ------ + Maria Odea Ching + ------ + 20 June 2006 + ------ + + +Using Alternate Doclet + + To generate output from an alternate doclet in addition to the project javadocs, add configuration + similar to the following to your POM: + +------------------ +<project> + ... + <reporting> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <reportSets> + <reportSet> + <id>uml</id> + <configuration> + <doclet>gr.spinellis.umlgraph.doclet.UmlGraph</doclet> + <docletArtifact> + <groupId>umlgraph</groupId> + <artifactId>UMLGraph</artifactId> + <version>4.2-SNAPSHOT</version> + </docletArtifact> + <additionalparam>-views</additionalparam> + <destDir>target/uml</destDir> + <show>private</show> + </configuration> + <reports> + <report>javadoc</report> + </reports> + </reportSet> + <reportSet> + <id>html</id> + <configuration> + <show>private</show> + </configuration> + <reports> + <report>javadoc</report> + </reports> + </reportSet> + </reportSets> + </plugin> + ... + </plugins> + </reporting> + ... +</project> +------------------ Added: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/excludePackageNames.apt URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/excludePackageNames.apt?rev=416295&view=auto ============================================================================== --- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/excludePackageNames.apt (added) +++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/excludePackageNames.apt Thu Jun 22 01:30:38 2006 @@ -0,0 +1,34 @@ + ------ + Excluding Packages + ------ + Maria Odea Ching + ------ + 20 June 2006 + ------ + + +Excluding Packages + + To exclude specific packages from the javadoc, make use of the excludePackageNames as shown below. The excludePackageNames + parameter accepts wildcard (*) characters in its value. + +------------------- +<project> + ... + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <configuration> + ... + <excludePackageNames>*.internal:org.apache.maven.plugin.javadoc.exclude1.*:org.apache.maven.plugin.javadoc.exclude2</excludePackageNames> + ... + </configuration> + </plugin> + </plugins> + ... + </build> + ... +</project> +------------------- Added: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/groupConfiguration.apt URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/groupConfiguration.apt?rev=416295&view=auto ============================================================================== --- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/groupConfiguration.apt (added) +++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/groupConfiguration.apt Thu Jun 22 01:30:38 2006 @@ -0,0 +1,42 @@ + ------ + Setting Group Configuration + ------ + Maria Odea Ching + ------ + 20 June 2006 + ------ + + +Setting Group Configuration + + To set a grouping for different packages, set the configuration specified below in your pom: + +------------------- +<project> + ... + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <configuration> + ... + <groups> + <group> + <title>Core Packages</title> + <packages>org.apache.maven.plugin.javadoc.test1</packages> + </group> + <group> + <title>Extension Packages</title> + <packages>org.apache.maven.plugin.javadoc.test2</packages> + </group> + </groups> + ... + </configuration> + </plugin> + </plugins> + ... + </build> + ... +</project> +------------------- Added: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/stylesheetConfiguration.apt URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/stylesheetConfiguration.apt?rev=416295&view=auto ============================================================================== --- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/stylesheetConfiguration.apt (added) +++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/stylesheetConfiguration.apt Thu Jun 22 01:30:38 2006 @@ -0,0 +1,37 @@ + ------ + Setting Stylesheet Configuration + ------ + Maria Odea Ching + ------ + 20 June 2006 + ------ + + +Setting Stylesheet Configuration + + If no custom stylesheet is specified in the "stylesheetfile" parameter, the stylesheet parameter will indicate + which stylesheet will be used--the stylesheet included in the maven javadoc plugin or the default stylesheet used by + the javadoc tool. "maven" indicates the maven javadoc plugin stylesheet, while "java" indicates the default javadoc + tool stylesheet. It defaults to "java" if no value is indicated. + +------------------- +<project> + ... + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <configuration> + ... + <stylesheet>maven</stylesheet> + ... + </configuration> + </plugin> + </plugins> + ... + </build> + ... +</project> +------------------- + Added: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tagConfiguration.apt URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tagConfiguration.apt?rev=416295&view=auto ============================================================================== --- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tagConfiguration.apt (added) +++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tagConfiguration.apt Thu Jun 22 01:30:38 2006 @@ -0,0 +1,40 @@ + ------ + Setting Tag Configuration + ------ + Maria Odea Ching + ------ + 20 June 2006 + ------ + + +Setting Tag Configuration + + To set a custom tag used in the javadoc, the following configuration must be set in the pom: + +------------------- +<project> + ... + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <configuration> + ... + <tags> + <tag> + <name>todo</name> + <!-- Should be a combinaison of the letters Xaoptcmf --> + <placement>a</placement> + <head>To do something:</head> + </tag> + </tags> + ... + </configuration> + </plugin> + </plugins> + ... + </build> + ... +</project> +------------------- Added: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/faq.apt URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/faq.apt?rev=416295&view=auto ============================================================================== --- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/faq.apt (added) +++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/faq.apt Thu Jun 22 01:30:38 2006 @@ -0,0 +1,13 @@ + ------ + FAQs + ------ + Maria Odea Ching + ------ + 21 June 2006 + ------ + + + +FAQs + + Below are frequently asked questions for the javadoc plugin: Added: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/overview.apt URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/overview.apt?rev=416295&view=auto ============================================================================== --- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/overview.apt (added) +++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/overview.apt Thu Jun 22 01:30:38 2006 @@ -0,0 +1,24 @@ + ------ + Overview + ------ + Maria Odea Ching + ------ + 18 May 2006 + ------ + + + +Overview + + + The Maven Javadoc Plugin uses the Javadoc tool to generate javadocs for the specified project. It gets the parameter values + that will be used from the plugin configuration specified in the pom. When no configuration values are set, the plugin sets + default values instead and then executes the Javadoc tool of the default Java installation in your machine. You can also use + the plugin to generate javadocs then package them in a jar file. + + + + + + + Added: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt?rev=416295&view=auto ============================================================================== --- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt (added) +++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt Thu Jun 22 01:30:38 2006 @@ -0,0 +1,83 @@ + ------ + Configuring Javadoc Report + ------ + Vincent Siveton + ------ + 01 March 2005 + ------ + +Usage + + The Javadoc Plugin generates javadocs using the Javadoc tool. Iterated below are the different goals and configuration for + generating them using the plugin. + +*Generate Javadoc + + To generate javadocs for the project, execute the following command: + +-------------------- +mvn javadoc:javadoc +-------------------- + +*Generate Javadoc Jar File + + The javadocs are generated first, then it will be packaged in a jar file. The javadoc:javadoc goal need not be + executed explicitly, the javadoc:jar goal will execute it and then package the generated javadocs. + + To generate a javadoc jar file for the project, execute the following command: + +-------------------- +mvn javadoc:jar +-------------------- + +*POM Configuration + + There are two ways to configure the javadoc plugin in your pom. The first one is configuring it on the <build> + section of the pom, as shown below. This configuration is viable when you want to explicitly execute the javadoc + plugin using 'mvn javadoc:javadoc' or 'mvn javadoc:jar'. + +------------------- +<project> + ... + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <configuration> + <minmemory>128m</minmemory> + <maxmemory>512</maxmemory> + ... + </configuration> + </plugin> + </plugins> + ... + </build> + ... +</project> +------------------- + + The other way is to configure the plugin in the <reporting> section of the pom as shown below. This generates the project + javadocs as part of the site generation (when 'mvn site' is executed). + +------------------- +<project> + ... + <reporting> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <configuration> + <minmemory>128m</minmemory> + <maxmemory>512</maxmemory> + ... + </configuration> + </plugin> + </plugins> + ... + </reporting> + ... +</project> +------------------ + Modified: maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml?rev=416295&r1=416294&r2=416295&view=diff ============================================================================== --- maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml (original) +++ maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml Thu Jun 22 01:30:38 2006 @@ -34,8 +34,17 @@ </links> <menu name="Overview"> - <item name="Introduction" href="/introduction.html" /> - <item name="Configuration" href="/configuration.html"/> + <item name="Overview" href="overview.html" /> + <item name="Usage" href="usage.html"/> + <item name="FAQs" href="faq.html" /> + </menu> + <menu name="Examples"> + <item name="Using Aggregate" href="/examples/aggregate.html" /> + <item name="Using Alternate Doclet" href="/examples/alternateDoclet.html" /> + <item name="Excluding Packages" href="/examples/excludePackageNames.html" /> + <item name="Setting Group Configuration" href="/examples/groupConfiguration.html" /> + <item name="Setting Stylesheet Configuration" href="/examples/stylesheetConfiguration.html" /> + <item name="Setting Tag Configuration" href="/examples/tagConfiguration.html" /> </menu> ${reports} </body>