You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by vs...@apache.org on 2009/09/11 14:50:26 UTC
svn commit: r813814 - in /maven/plugins/trunk/maven-javadoc-plugin/src/site:
apt/usage.apt.vm fml/faq.fml
Author: vsiveton
Date: Fri Sep 11 12:50:25 2009
New Revision: 813814
URL: http://svn.apache.org/viewvc?rev=813814&view=rev
Log:
o improved doc due to r813812
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt.vm
maven/plugins/trunk/maven-javadoc-plugin/src/site/fml/faq.fml
Modified: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt.vm
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt.vm?rev=813814&r1=813813&r2=813814&view=diff
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt.vm (original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt.vm Fri Sep 11 12:50:25 2009
@@ -4,7 +4,7 @@
Vincent Siveton
Maria Odea Ching
------
- 2009-08-04
+ 2009-09-11
------
~~ Licensed to the Apache Software Foundation (ASF) under one
@@ -35,7 +35,7 @@
* Generate Javadocs As Part Of Project Reports
- To generate javadocs as part of the site generation, you must configure the following in the \<reporting\> section of your pom:
+ To generate javadocs as part of the site generation, you should add the Javadoc Plugin in the \<reporting\> section of your pom:
+-----+
<project>
@@ -46,6 +46,9 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>${project.version}</version>
+ <configuration>
+ ...
+ </configuration>
</plugin>
</plugins>
...
@@ -59,24 +62,95 @@
* Generate Standalone Javadocs
- To generate standalone javadocs for the project, you can execute any of the following commands:
+ To generate standalone javadocs for the project, you could add the Javadoc Plugin in the \<build\> section of your pom
+ (if no configuration defined, the plugin uses default values):
+-----+
-mvn javadoc:javadoc
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ ...
+ </configuration>
+ </plugin>
+ </plugins>
+ ...
+ </build>
+ ...
+</project>
+-----+
- or
+ And execute any of the following commands:
+-----+
+mvn javadoc:javadoc
mvn javadoc:jar
+mvn javadoc:aggregate
+mvn javadoc:aggregate-jar
+mvn javadoc:test-javadoc
+mvn javadoc:test-jar
+mvn javadoc:test-aggregate
+mvn javadoc:test-aggregate-jar
+-----+
- For <<<mvn javadoc:jar>>>, the javadocs are first generated and then packaged into a jar file.
+ For all <<<jar>>> goals, the javadocs are first generated and then packaged into a jar file.
* Javadoc Configuration
The Javadoc Plugin supports a large number of configuration parameters. Each configuration parameter turns into
a tag name.
- Please see the {{{./apidocs/org/apache/maven/plugin/javadoc/package-summary.html}Javadoc Package Summary}}
- for a listing of these parameters. Most of these parameters are passed directly to the Javadoc tool itself.
+ Please refer to the {{{../javadoc-mojo.html}Javadoc Plugin Documentation}} for a listing of these parameters. Most
+ of these parameters are passed directly to the Javadoc tool itself.
+
+ <<IMPORTANT NOTE>>: configuring the Javadoc plugin in the \<reporting/\> or \<build/\> elements in the pom have
+ <<NOT>> the same behavior as described in the
+ {{{http://maven.apache.org/guides/mini/guide-configuring-plugins.html#Using_the_reporting_Tag_VS_build_Tag}Guide to Configuring Plug-ins}}.
+
+ For instance, if you have the following snippet:
+
++-----+
+<project>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <show>private</show>
+ <nohelp>true</nohelp>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <stylesheetfile>${basedir}/src/main/javadoc/stylesheet.css</stylesheetfile>
+ <show>public</show>
+ </configuration>
+ </plugin>
+ </plugins>
+ </reporting>
+ </build>
++-----+
+
+ [<<<mvn site>>>] It will generate the Javadoc for public members (defined in \<reporting/\>) using the given
+ stylesheet (defined in \<reporting/\>), and with an help page (default value for
+ {{{../javadoc-mojo.html#nohelp}nohelp}} is true).
+
+ [<<<mvn javadoc:javadoc>>>] It will generate the Javadoc for private members (defined in \<build/\>) using the
+ stylesheet (defined in \<reporting/\>), and with no help page (defined in \<build/\>).
+
+ []
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=813814&r1=813813&r2=813814&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 Fri Sep 11 12:50:25 2009
@@ -21,8 +21,8 @@
<faqs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns="http://maven.apache.org/FML/1.0"
- xsi:schemaLocation="http://maven.apache.org/FML/1.0 http://maven.apache.org/xsd/fml-1.0.xsd"
+ xmlns="http://maven.apache.org/FML/1.0.1"
+ xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
id="FAQ" title="Frequently Asked Questions">
<part id="General">
<faq id="What are the Javadoc options supported by the Maven Javadoc Plugin">
@@ -32,7 +32,7 @@
All options provided by Sun on the Javadoc homepages are wrapped in the Maven Javadoc Plugin. This
plugin supports Javadoc 1.4, 1.5 and 6.0 options. Refer you to the
<a href="./apidocs/org/apache/maven/plugin/javadoc/package-summary.html">Javadoc Package Summary</a>
- for more information.
+ for more information and to the <a href="./javadoc-mojo.html">Javadoc Plugin Documentation</a>.
</p>
</answer>
</faq>
@@ -40,13 +40,17 @@
<question>Where in the pom.xml do I configure the Javadoc Plugin?</question>
<answer>
<p>
- Like all other site report plugins, the Javadoc Plugin goes in the <i><reporting/></i> section
+ Like all other reporting plugins, the Javadoc Plugin goes in the <i><reporting/></i> section
of your pom.xml. In this case, you will need to call <code>mvn site</code> to run reports.
</p>
<p>
- You could also configure it in the <plugins/> or <pluginsManagement/> in <build/> tag
- of your pom.xml. In this case, you will need to call <code>mvn javadoc:javadoc</code> to run the main
- report.
+ You could also configure it in the <i><plugins/></i> or <i><pluginsManagement/></i> in
+ <i><build/></i> tag of your pom.xml. In this case, you will need to call
+ <code>mvn javadoc:javadoc</code> to run the main report.
+ </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.
</p>
</answer>
</faq>
@@ -226,12 +230,12 @@
To deploy the Javadoc jar on a given Maven repository, you could call:
<source><![CDATA[
mvn deploy:deploy-file \
- -DgroupId=<group-id> \
- -DartifactId=<artifact-id> \
- -Dversion=<version> \
- -Dfile=<path-to-file> \
+ -DgroupId=<group-id> \
+ -DartifactId=<artifact-id> \
+ -Dversion=<version> \
+ -Dfile=<path-to-file> \
-Dpackaging=jar \
- -DrepositoryId=<repository-id> \
+ -DrepositoryId=<repository-id> \
-Durl=dav:http://www.myrepository.com/m2 \
-Dclassifier=javadoc]]></source>
</p>
@@ -250,18 +254,27 @@
</answer>
</faq>
<faq id="How to use links option in Standard Doclet">
- <question>How to use links option in Standard Doclet?</question>
+ <question>How to use <i><a href="./javadoc-mojo.html#links"><links/></a></i> option in Standard Doclet?</question>
<answer>
<p>
- You need to configure the <i><links/></i> parameter. Also, you need to correctly write references in
- your Javadoc, i.e.:
+ You need to configure the <i><a href="./javadoc-mojo.html#links"><links/></a></i> parameter. Also, you
+ should correctly write references in your Javadoc, i.e.:
</p>
<ul>
<li><code>@see MyMojo</code> or <code>{@link MyMojo}</code> will <b>NOT work</b>.</li>
- <li><code>@see com.mycompany.plugin.myplugin.MyMojo</code> or <code>{@link com.mycompany.myplugin.MyMojo}</code> will <b>work</b>.</li>
+ <li><code>@see com.mycompany.plugin.myplugin.MyMojo</code> or <code>{@link com.mycompany.myplugin.MyMojo}</code>
+ will <b>work</b>.</li>
</ul>
</answer>
</faq>
+ <faq id="How to add cross reference link to internal-external projects">
+ <question>How to add cross reference link to internal-external projects?</question>
+ <answer>
+ <p>
+ Please refer to <a href="./examples/links-configuration.html">Links configuration page</a>.
+ </p>
+ </answer>
+ </faq>
<faq id="On Windows with Sun JDK, why javadoc:javadoc goal blows up due to an IllegalArgumentException in sun.net.www.ParseUtil.decode()">
<question>On Windows with Sun JDK, why <i>javadoc:javadoc</i> goal blows up due to an IllegalArgumentException in <i>sun.net.www.ParseUtil.decode()</i>?</question>
<answer>
@@ -403,13 +416,5 @@
</dl>
</answer>
</faq>
- <faq id="How to add cross reference link to internal-external projects">
- <question>How to add cross reference link to internal-external projects?</question>
- <answer>
- <p>
- Please refer to <a href="./examples/links-configuration.html">Links configuration page</a>.
- </p>
- </answer>
- </faq>
</part>
</faqs>
\ No newline at end of file