Author: mperham
Date: Tue Jul 11 09:07:10 2006
New Revision: 420909
URL: http://svn.apache.org/viewvc?rev=420909&view=rev
Log:
Documentation review updates
Added:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-doclet.apt
- copied, changed from r420895,
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternatedoclet.apt
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/exclude-package-names.apt
- copied, changed from r420895,
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/excludepackagenames.apt
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/group-configuration.apt
- copied, changed from r420895,
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/groupconfiguration.apt
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/stylesheet-configuration.apt
- copied, changed from r420895,
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/stylesheetconfiguration.apt
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tag-configuration.apt
- copied, changed from r420895,
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tagconfiguration.apt
Removed:
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
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate.apt
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/index.apt
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
maven/plugins/trunk/maven-javadoc-plugin/src/site/fml/faq.fml
maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml
Modified:
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=420909&r1=420908&r2=420909&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate.apt
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate.apt
Tue Jul 11 09:07:10 2006
@@ -3,16 +3,16 @@
------
Maria Odea Ching
------
- 20 June 2006
+ June 2006
------
Aggregating Javadocs for Multi-Projects
- 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.
+ The \<aggregate\> parameter can be used to generate javadocs for multi-module
projects. It gives the option to
+ generate one javadoc report for the entire project (all modules) or generate
one javadoc report for each module.
- For example, you have the following directory structure:
+ For example, consider the following directory structure:
+-----+
@@ -20,16 +20,16 @@
|-- pom.xml
|-- Module1
| `-- pom.xml
-|-- Module1
+|-- Module2
| `-- pom.xml
-`-- Module1
+`-- Module3
`-- pom.xml
+-----+
- 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
+ When you execute javadoc from Project directory with aggregate set to
<<true>>, a javadoc report will be created
+ in the target directory of Project with all the javadocs of Project's modules
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.
Copied:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-doclet.apt
(from r420895,
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/alternate-doclet.apt?p2=maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-doclet.apt&p1=maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternatedoclet.apt&r1=420895&r2=420909&rev=420909&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternatedoclet.apt
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/alternate-doclet.apt
Tue Jul 11 09:07:10 2006
@@ -4,7 +4,7 @@
Vincent Siveton
Maria Odea Ching
------
- 20 June 2006
+ June 2006
------
Copied:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/exclude-package-names.apt
(from r420895,
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/exclude-package-names.apt?p2=maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/exclude-package-names.apt&p1=maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/excludepackagenames.apt&r1=420895&r2=420909&rev=420909&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/excludepackagenames.apt
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/exclude-package-names.apt
Tue Jul 11 09:07:10 2006
@@ -3,15 +3,15 @@
------
Maria Odea Ching
------
- 20 June 2006
+ June 2006
------
Excluding Packages
- To exclude specific packages from the javadoc, make use of the
excludePackageNames parameter as shown below. The parameter
- accepts wildcard (*) characters in its value. But the wildcards should either
be at the start of the package name or at the
- end. If more than one package is to be excluded, each package name must be
separated either with a ':', ',' or ';'.
+ To exclude specific packages from the javadoc, use \<excludePackageNames\> 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 ':', ',' or ';'.
+-----+
<project>
@@ -23,7 +23,7 @@
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
...
-
<excludePackageNames>*.internal:org.apache.maven.plugin.javadoc.exclude1.*:org.apache.maven.plugin.javadoc.exclude2</excludePackageNames>
+
<excludePackageNames>*.internal:org.acme.exclude1.*:org.acme.exclude2</excludePackageNames>
...
</configuration>
</plugin>
Copied:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/group-configuration.apt
(from r420895,
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/group-configuration.apt?p2=maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/group-configuration.apt&p1=maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/groupconfiguration.apt&r1=420895&r2=420909&rev=420909&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/groupconfiguration.apt
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/group-configuration.apt
Tue Jul 11 09:07:10 2006
@@ -4,13 +4,13 @@
Vincent Siveton
Maria Odea Ching
------
- 20 June 2006
+ June 2006
------
Grouping Packages
- To set a grouping for different packages, set the configuration specified
below in your pom:
+ To set a grouping for different packages, use the \<groups\> configuration in
your pom:
+-----+
<project>
Copied:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/stylesheet-configuration.apt
(from r420895,
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/stylesheet-configuration.apt?p2=maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/stylesheet-configuration.apt&p1=maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/stylesheetconfiguration.apt&r1=420895&r2=420909&rev=420909&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/stylesheetconfiguration.apt
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/stylesheet-configuration.apt
Tue Jul 11 09:07:10 2006
@@ -3,16 +3,16 @@
------
Maria Odea Ching
------
- 20 June 2006
+ June 2006
------
Configuring Stylesheets
- If no custom stylesheet is specified in the stylesheetfile parameter, the
stylesheet parameter will indicate
+ 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.
+ the javadoc tool. <<maven>> indicates the maven javadoc plugin stylesheet,
while <<java>> indicates the default javadoc
+ tool stylesheet. The default is <<java>> if not specified.
+-----+
<project>
Copied:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tag-configuration.apt
(from r420895,
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/tag-configuration.apt?p2=maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tag-configuration.apt&p1=maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tagconfiguration.apt&r1=420895&r2=420909&rev=420909&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tagconfiguration.apt
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/tag-configuration.apt
Tue Jul 11 09:07:10 2006
@@ -4,13 +4,13 @@
Vincent Siveton
Maria Odea Ching
------
- 20 June 2006
+ June 2006
------
Configuring Custom Javadoc Tags
- To set a custom tag used in the javadoc, the following configuration must be
set in the pom:
+ You can configure any custom tags used in your javadoc via the \<tags\>
element:
+-----+
<project>
@@ -25,7 +25,7 @@
<tags>
<tag>
<name>todo</name>
- <!-- Should be a combinaison of the letters Xaoptcmf -->
+ <!-- Should be a combination of the letters Xaoptcmf -->
<placement>a</placement>
<head>To do something:</head>
</tag>
Modified: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/index.apt?rev=420909&r1=420908&r2=420909&view=diff
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/index.apt (original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/index.apt Tue Jul 11
09:07:10 2006
@@ -7,25 +7,25 @@
------
-
Maven 2 Javadoc Plugin
The Javadoc Plugin uses the Javadoc tool to generate javadocs for the
specified project. For more information about the
standard Javadoc tool, see
{{{http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html}here}}.
- The Javadoc Plugin gets the parameter values that will be used from the
plugin configuration specified in the pom.
+ The Javadoc Plugin 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.
- You can also use the plugin to generate javadocs then package them in a jar
file.
+ You can also use the plugin to package the generated javadocs into a jar file
for distribution.
* Goals Overview
The Javadoc Plugin has two goals:
- * {{{javadoc-mojo.html}javadoc:javadoc}} is used to generate the javadoc
files for the project. It uses the standard
- Javadoc tool to generate the javadocs and supports the parameters used by
the tool.
+ * {{{javadoc-mojo.html}javadoc:javadoc}} generates the javadoc files for
the project. It executes the standard
+ Javadoc tool and supports the parameters used by the tool.
- * {{{jar-mojo.html}javadoc:jar}} is used to create an archive file of the
generated javadocs. It is mostly used when
- releasing to publish to the repository.
+ * {{{jar-mojo.html}javadoc:jar}} creates an archive file of the generated
javadocs. It is used during
+ the release process to create the javadoc artifact for the project's
release. This artifact is uploaded
+ to the remote repository along with the project's compiled binary and
source archive.
* Usage
@@ -33,20 +33,19 @@
* Examples
- To provide you with better understanding on some usages of the Javadoc
plugin, you can take a look into the
- following examples:
+ The following examples show how to use the Javadoc Plugin in more advanced
usecases:
* {{{examples/aggregate.html}Aggregating Javadocs for Multi-Projects}}
- * {{{examples/alternatedoclet.html}Using Alternate Doclet}}
+ * {{{examples/alternate-doclet.html}Using Alternate Doclet}}
- * {{{examples/excludepackagenames.html}Excluding Packages}}
+ * {{{examples/exclude-package-names.html}Excluding Packages}}
- * {{{examples/groupconfiguration.html}Grouping Packages}}
+ * {{{examples/group-configuration.html}Grouping Packages}}
- * {{{examples/stylesheetconfiguration.html}Configuring Stylesheets}}
+ * {{{examples/stylesheet-configuration.html}Configuring Stylesheets}}
- * {{{examples/tagconfiguration.html}Configuring Custom Javadoc Tags}}
+ * {{{examples/tag-configuration.html}Configuring Custom Javadoc Tags}}
Modified: 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=420909&r1=420908&r2=420909&view=diff
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt (original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt Tue Jul 11
09:07:10 2006
@@ -9,8 +9,8 @@
Usage
- The Javadoc Plugin generates javadocs using the Javadoc tool. Iterated below
are the different goals and configuration for
- generating them using the plugin.
+ The Javadoc Plugin generates javadocs using the Javadoc tool. The following
examples describe the basic usage of the
+ Plugin.
* Generate Javadocs As Part of Project Reports
@@ -38,7 +38,7 @@
+-----+
When you execute <<<mvn site>>>, the javadocs will be generated and included
in the generated site. A link to the javadocs
- will be added in the Project Reports.
+ will be added in the Project Reports menu.
* Generate Standalone Javadocs
@@ -54,29 +54,10 @@
mvn javadoc:jar
+-----+
- For <<<mvn javadoc:jar>>>, the javadocs are generated first then it will be
archived in a jar file. The {{{jar-mojo.html}javadoc:jar}}
- goal is run by default and is mostly used when releasing to publish to the
repository.
+ For <<<mvn javadoc:jar>>>, the javadocs are first generated and then packaged
into a jar file.
- You should only configure the plugin in the \<build\> section of your pom
file, as shown below, if and only if the configuration is
- different to the configuration on the site or the report is not included on
the site at all.
+* Javadoc Configuration
-+-----+
-<project>
- ...
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-javadoc-plugin</artifactId>
- <configuration>
- <minmemory>128m</minmemory>
- <maxmemory>512m</maxmemory>
- ...
- </configuration>
- </plugin>
- </plugins>
- ...
- </build>
- ...
-</project>
-+-----+
+ The Javadoc Plugin supports a large number of configuration parameters.
Please see the {{{javadoc-mojo.html}javadoc:javadoc}}
+ goal documentation for a listing of these parameters. Most of these
parameters are passed directly to the javadoc tool
+ itself. More info on the Javadoc tool can be found
{{{http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html}here}}.
\ No newline at end of file
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=420909&r1=420908&r2=420909&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 Tue Jul 11
09:07:10 2006
@@ -1,9 +1,9 @@
<?xml version="1.0"?>
<faqs id="FAQ" title="Frequently Asked Questions">
<part id="General">
- <faq id="In which part of the pom.xml does the Javadoc plugin should be
configured">
- <question>In which part of the pom.xml does the Javadoc plugin should be
configured?</question>
- <answer><p>You can configura the Javadoc plugin in the <i>reporting</i>
section of your pom.xml if you want to include it in the site generation
process (e.g. mvn site). You can also configure it in the <i>build</i> section
of your pom if the configuration is different on the site or the report is not
included on the site at all.</p></answer>
+ <faq id="Where in the pom.xml do I configure the Javadoc plugin?">
+ <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 of your pom.xml.</p></answer>
</faq>
</part>
</faqs>
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=420909&r1=420908&r2=420909&view=diff
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml (original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml Tue Jul 11
09:07:10 2006
@@ -35,17 +35,17 @@
<menu name="Overview">
<item name="Introduction" href="index.html"/>
- <item name="Goals" href="plugin-info.html"/>
<item name="Usage" href="usage.html"/>
- <item name="FAQs" href="faq.html"/>
+ <item name="Goals" href="plugin-info.html"/>
+ <item name="FAQ" href="faq.html"/>
</menu>
<menu name="Examples">
- <item name="Aggregating Javadocs for Multi-Projects"
href="/examples/aggregate.html"/>
- <item name="Using Alternate Doclet"
href="/examples/alternatedoclet.html"/>
- <item name="Excluding Packages"
href="/examples/excludepackagenames.html"/>
- <item name="Grouping Packages" href="/examples/groupconfiguration.html"/>
- <item name="Configuring Stylesheets"
href="/examples/stylesheetconfiguration.html"/>
- <item name="Configuring Custom Javadoc Tags"
href="/examples/tagconfiguration.html"/>
+ <item name="Aggregating Javadocs" href="/examples/aggregate.html"/>
+ <item name="Using Alternate Doclets"
href="/examples/alternate-doclet.html"/>
+ <item name="Excluding Packages"
href="/examples/exclude-package-names.html"/>
+ <item name="Grouping Packages"
href="/examples/group-configuration.html"/>
+ <item name="Configuring Stylesheets"
href="/examples/stylesheet-configuration.html"/>
+ <item name="Configuring Custom Tags"
href="/examples/tag-configuration.html"/>
</menu>
${reports}
</body>
