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/02/23 11:58:24 UTC
svn commit: r746958 [3/3] - in /maven/plugins/trunk/maven-javadoc-plugin: ./
src/it/MJAVADOC-226/ src/it/MJAVADOC-226/src/ src/it/MJAVADOC-226/src/main/
src/it/MJAVADOC-226/src/main/java/ src/it/MJAVADOC-226/src/main/java/fix/
src/it/MJAVADOC-226/src/m...
Propchange: maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/AbstractFixJavadocMojo.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/AbstractFixJavadocMojo.java
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Added: maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/FixJavadocMojo.java
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/FixJavadocMojo.java?rev=746958&view=auto
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/FixJavadocMojo.java (added)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/FixJavadocMojo.java Mon Feb 23 10:58:23 2009
@@ -0,0 +1,51 @@
+package org.apache.maven.plugin.javadoc;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import java.io.File;
+
+/**
+ * Fix Javadoc documentation and tags for the <code>Java code</code> for the project.
+ * See <a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#wheretags">Where Tags Can Be Used</a>.
+ *
+ * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
+ * @version $Id$
+ * @since 2.5.1
+ * @goal fix
+ * @requiresDependencyResolution compile
+ * @execute phase="compile"
+ */
+public class FixJavadocMojo
+ extends AbstractFixJavadocMojo
+{
+ /**
+ * The classes of this project to compare the last release against.
+ * Used by {@link AbstractFixJavadocMojo.ClirrMojoWrapper} class.
+ *
+ * @parameter default-value="${project.build.outputDirectory}
+ */
+ private File classesDirectory;
+
+ /** {@inheritDoc} */
+ protected File getClassesDirectory()
+ {
+ return classesDirectory;
+ }
+}
Propchange: maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/FixJavadocMojo.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/FixJavadocMojo.java
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Added: maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/TestFixJavadocMojo.java
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/TestFixJavadocMojo.java?rev=746958&view=auto
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/TestFixJavadocMojo.java (added)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/TestFixJavadocMojo.java Mon Feb 23 10:58:23 2009
@@ -0,0 +1,96 @@
+package org.apache.maven.plugin.javadoc;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import java.io.File;
+import java.util.Collections;
+import java.util.List;
+
+import org.apache.maven.artifact.DependencyResolutionRequiredException;
+import org.apache.maven.plugin.MojoExecutionException;
+import org.apache.maven.plugin.MojoFailureException;
+import org.apache.maven.project.MavenProject;
+
+/**
+ * Fix Javadoc documentation and tags for the <code>Test Java code</code> for the project.
+ * See <a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#wheretags">Where Tags Can Be Used</a>.
+ *
+ * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
+ * @version $Id$
+ * @since 2.5.1
+ * @goal test-fix
+ * @requiresDependencyResolution test
+ * @execute phase="test-compile"
+ */
+public class TestFixJavadocMojo
+ extends AbstractFixJavadocMojo
+{
+ /**
+ * The classes of this project to compare the last release against.
+ * Used by {@link AbstractFixJavadocMojo.ClirrMojoWrapper} class.
+ *
+ * @parameter default-value="${project.build.testOutputDirectory}
+ */
+ private File classesDirectory;
+
+ /** {@inheritDoc} */
+ protected File getClassesDirectory()
+ {
+ return classesDirectory;
+ }
+
+ /** {@inheritDoc} */
+ protected List getProjectSourceRoots( MavenProject p )
+ {
+ if ( "pom".equals( p.getPackaging().toLowerCase() ) )
+ {
+ if ( getLog().isWarnEnabled() )
+ {
+ getLog().warn( "This project has 'pom' packaging, no test Java sources will be available." );
+ }
+ return Collections.EMPTY_LIST;
+ }
+
+ return p.getTestCompileSourceRoots();
+ }
+
+ /** {@inheritDoc} */
+ protected List getCompileClasspathElements( MavenProject p )
+ throws DependencyResolutionRequiredException
+ {
+ return p.getTestClasspathElements();
+ }
+
+ /** {@inheritDoc} */
+ protected String getArtifactType( MavenProject p )
+ {
+ return "test-jar";
+ }
+
+ /** {@inheritDoc} */
+ protected void executeClirr()
+ throws MojoExecutionException, MojoFailureException
+ {
+ // clirr doesn't analyze test code, so ignore it
+ ignoreClirr = true;
+
+ return;
+ }
+}
Propchange: maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/TestFixJavadocMojo.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/TestFixJavadocMojo.java
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Added: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/fix-javadocs.apt
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/fix-javadocs.apt?rev=746958&view=auto
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/fix-javadocs.apt (added)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/fix-javadocs.apt Mon Feb 23 10:58:23 2009
@@ -0,0 +1,82 @@
+ ------
+ Fixing Javadoc Comments
+ ------
+ Vincent Siveton
+ ------
+ 2009-02-22
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Fixing Javadoc Comments
+
+ When developers write code, they could forget to create (or update) the Javadoc comments. The <fix> and <test-fix>
+ goals are interactive goals to fix the actual Javadoc comments.
+
+ You need to call <mvn javadoc:fix> to fix main Java source files (i.e. inside src/main/java directory) or
+ <mvn javadoc:test-fix> to fix test Java source files (i.e. inside src/test/java directory).
+
+ <<Important Note>>: Since the changes are done <<directly>> in the source code, we recommend <<strongly>> the use of
+ a SCM, so you could always do a revert if a problem occurs.
+
+* Feature Summary
+
+ The user could skip the class/field/method Javadoc fixing using specific parameters, i.e.
+ {{{../fix-mojo.html#fixClassComment}fixClassComment}}.
+ Also, the user could specify a {{{../fix-mojo.html#level}level}}, i.e. public, to fix only class/field/method with
+ the given level.
+
+ These goals could fix dynamically all Javadoc tags (by default, see {{{../fix-mojo.html#fixTags}fixTags}}) or
+ selective tags like author, version...
+ Also, the user could specify default value for some tags, i.e. {{{../fix-mojo.html#defaultAuthor}defaultAuthor}}.
+
+ The <javadoc:fix> goal could use {{{http://clirr.sourceforge.net/}Clirr}}, a tool that checks Java libraries for
+ binary and source compatibility with older releases. So, the <@since> tags will be dynamically added for the current
+ project version. You need to add the <comparisonVersion> parameter.
+
+ Finally, the user could process specific Java files using the
+ {{{../fix-mojo.html#includes}includes}}/{{{../fix-mojo.html#excludes}excludes}} parameters.
+
+* Example Call
+
++-----+
+mvn org.apache.maven.plugins:maven-javadoc-plugin:2.5.1:fix -DcomparisonVersion=1.0
+...
+[INFO] [javadoc:fix]
+[WARNING]
+
+[WARNING] WARRANTY DISCLAIMER
+[WARNING]
+
+[WARNING] All warranties with regard to this Maven goal are disclaimed!
+[WARNING] The Maven Team strongly recommends the use of a SCM software BEFORE executing this goal.
+[INFO] Are you sure to proceed? [Y]es [N]o
+y
+[INFO] OK, let's proceed...
+[debug] Comparing to <groupId>:<artifactId>:1.0:null:jar
+[INFO] Clirr found Api differences.
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESSFUL
+[INFO] ------------------------------------------------------------------------
+...
++-----+
+
+ You could review the changes and commit.
Propchange: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/fix-javadocs.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/fix-javadocs.apt
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
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=746958&r1=746957&r2=746958&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 Mon Feb 23 10:58:23 2009
@@ -4,7 +4,7 @@
Maria Odea Ching
Vincent Siveton
------
- 2008-06-01
+ 2009-02-22
------
~~ Licensed to the Apache Software Foundation (ASF) under one
@@ -49,7 +49,7 @@
* Goals Overview
- The Javadoc Plugin has six goals:
+ The Javadoc Plugin has eight goals:
* {{{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.
@@ -69,6 +69,12 @@
* {{{test-jar-mojo.html}javadoc:test-jar}} creates an archive file of the generated Test Javadocs.
+ * {{{fix-mojo.html}javadoc:fix}} is an interactive goal which fixes the Javadoc documentation and tags for the Java files.
+
+ * {{{test-fix-mojo.html}javadoc:test-fix}} is an interactive goal which fixes the Javadoc documentation and tags for the test Java files.
+
+ []
+
* Usage
General instructions on how to use the Javadoc Plugin can be found on the {{{usage.html}usage page}}. Some more
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=746958&r1=746957&r2=746958&view=diff
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml (original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml Mon Feb 23 10:58:23 2009
@@ -45,6 +45,7 @@
<item name="Configuring Custom Taglets" href="/examples/taglet-configuration.html"/>
<item name="Generating Test Javadocs" href="/examples/test-javadocs.html"/>
<item name="Selective Javadocs Reports" href="/examples/selective-javadocs-report.html"/>
+ <item name="Fixing Javadoc Comments" href="/examples/fix-javadocs.html"/>
</menu>
</body>
</project>