Author: vsiveton
Date: Wed Mar 1 14:32:57 2006
New Revision: 382183
URL: http://svn.apache.org/viewcvs?rev=382183&view=rev
Log:
PR: MJAVADOC-59: Refactoring tag option
Updated documentation and tests.
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocReport.java
maven/plugins/trunk/maven-javadoc-plugin/src/main/mdo/javadocOptions.mdo
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/configuration.apt
maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml
maven/plugins/trunk/maven-javadoc-plugin/src/test/projects/javadoc-plugin-test1/pom.xml
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocReport.java
URL:
http://svn.apache.org/viewcvs/maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocReport.java?rev=382183&r1=382182&r2=382183&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
Wed Mar 1 14:32:57 2006
@@ -34,6 +34,7 @@
import org.apache.maven.artifact.handler.ArtifactHandler;
import org.apache.maven.model.Model;
import org.apache.maven.plugin.javadoc.options.Group;
+import org.apache.maven.plugin.javadoc.options.Tag;
import org.apache.maven.project.MavenProject;
import org.apache.maven.reporting.AbstractMavenReport;
import org.apache.maven.reporting.MavenReportException;
@@ -322,7 +323,15 @@
/**
* Separates packages on the overview page into whatever groups you
specify, one group per table.
* See <a
href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#group";>group</a>.
- * It is a comma separated String.
+ * Example:
+ * <pre>
+ * <groups>
+ * <group>
+ * <title>Core Packages</title>
+ * <packages>org.apache.core</packages>
+ * </group>
+ * </groups>
+ * </pre>
*
* @parameter expression="${groups}"
*/
@@ -468,25 +477,22 @@
private String stylesheetfile;
/**
- * Contains a list of tag names, which will result in conversion to
support the following, from the javadoc
- * API:
- * <br/>
* Enables the Javadoc tool to interpret a simple, one-argument custom
block tag tagname in doc comments.
* See <a
href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#tag";>tag</a>.
- * It is a comma separated String.
+ * Example:
+ * <pre>
+ * <tags>
+ * <tag>
+ * <name>todo</name>
+ * <placement>a</placement>
+ * <head>To Do:</head>
+ * </tag>
+ * </tags>
+ * </pre>
*
* @parameter expression="${tags}"
*/
- private ArrayList tags;
-
- /**
- * Enables the Javadoc tool to interpret a simple, one-argument custom
block tag tagname in doc comments.
- * See <a
href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#tag";>tag</a>.
- * It is a comma separated String.
- *
- * @parameter expression="${tag}"
- */
- private String tag;
+ private Tag[] tags;
/**
* Specifies the class file that starts the taglet used in generating the
documentation for that tag.
@@ -882,20 +888,26 @@
addArgIf( arguments, splitindex, "-splitindex" );
addArgIfNotEmpty( arguments, "-stylesheetfile",
quotedPathArgument( stylesheetfile ) );
- addArgIfNotEmpty( arguments, "-tag", quotedArgument( tag ), 1.4f,
true );
+ addArgIfNotEmpty( arguments, "-taglet", quotedArgument( taglet ),
1.4f );
+ addArgIfNotEmpty( arguments, "-tagletpath", quotedPathArgument(
tagletpath ), 1.4f );
- if ( tags != null && !tags.isEmpty() )
+ for ( int i = 0; i < tags.length; i++ )
{
- for ( Iterator it = tags.iterator(); it.hasNext(); )
+ if ( ( tags[i] == null ) || ( StringUtils.isEmpty(
tags[i].getName() ) )
+ || ( StringUtils.isEmpty( tags[i].getPlacement() ) ) )
{
- String tag = (String) it.next();
-
- addArgIfNotEmpty( arguments, "-tag", quotedArgument( tag
), 1.4f, true );
+ getLog().info( "A tag option is empty. Ignore this
option." );
+ continue;
+ }
+ String value = "\"" + tags[i].getName() + ":" +
tags[i].getPlacement();
+ if ( !StringUtils.isEmpty( tags[i].getHead() ) )
+ {
+ value += ":" + quotedArgument( tags[i].getHead() );
}
+ value+="\"";
+ addArgIfNotEmpty( arguments, "-tag", value, 1.4f, false );
}
- addArgIfNotEmpty( arguments, "-taglet", quotedArgument( taglet ),
1.4f );
- addArgIfNotEmpty( arguments, "-tagletpath", quotedPathArgument(
tagletpath ), 1.4f );
addArgIf( arguments, use, "-use" );
addArgIf( arguments, version, "-version" );
addArgIfNotEmpty( arguments, "-windowtitle", quotedArgument(
windowtitle ) );
@@ -918,7 +930,10 @@
throw new MavenReportException( "Unable to write temporary
file for command execution", e );
}
cmd.createArgument().setValue( "@options" );
- optionsFile.deleteOnExit();
+ if ( !getLog().isDebugEnabled() )
+ {
+ optionsFile.deleteOnExit();
+ }
}
cmd.createArgument().setValue( "@files" );
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/main/mdo/javadocOptions.mdo
URL:
http://svn.apache.org/viewcvs/maven/plugins/trunk/maven-javadoc-plugin/src/main/mdo/javadocOptions.mdo?rev=382183&r1=382182&r2=382183&view=diff
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/main/mdo/javadocOptions.mdo
(original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/main/mdo/javadocOptions.mdo
Wed Mar 1 14:32:57 2006
@@ -32,6 +32,88 @@
</field>
</fields>
</class>
+
+ <class>
+ <name>Tag</name>
+ <description>A Tag parameter.</description>
+ <version>1.0.0</version>
+ <fields>
+ <field>
+ <name>name</name>
+ <description>Name of the tag.</description>
+ <version>1.0.0</version>
+ <type>String</type>
+ <identifier>true</identifier>
+ </field>
+ <field>
+ <name>head</name>
+ <description>Head of the tag.</description>
+ <version>1.0.0</version>
+ <type>String</type>
+ <identifier>true</identifier>
+ </field>
+ </fields>
+ <codeSegments>
+ <codeSegment>
+ <version>1.0.0</version>
+ <code><![CDATA[
+ /**
+ * Field placement
+ */
+ private String placement;
+
+ /**
+ * Get the placement.
+ */
+ public String getPlacement()
+ {
+ return this.placement;
+ }
+
+ /**
+ * Set a Placement. Should be a combinaison of the letters:
+ * <ul>
+ * <li> X (disable tag)</li>
+ * <li> a (all)</li>
+ * <li> o (overview)</li>
+ * <li> p (packages)</li>
+ * <li> t (types, that is classes and interfaces)</li>
+ * <li> c (constructors)</li>
+ * <li> m (methods)</li>
+ * <li> f (fields)</li>
+ * </ul>
+ *
+ * @param placement
+ * @throws IllegalArgumentException if not a valid combinaison of the
letters
+ */
+ public void setPlacement(String placement)
+ throws IllegalArgumentException
+ {
+ char[] chars = placement.toCharArray();
+ for ( int i = 0; i < chars.length; i++ )
+ {
+ switch ( chars[i] )
+ {
+ case 'X':
+ case 'a':
+ case 'o':
+ case 'p':
+ case 't':
+ case 'c':
+ case 'm':
+ case 'f':
+ break;
+ default:
+ throw new IllegalArgumentException( "Placement should be a
combinaison of the letters 'Xaoptcmf'." );
+ }
+ }
+ this.placement = placement;
+ }
+
+ ]]></code>
+ </codeSegment>
+ </codeSegments>
+ </class>
</classes>
</model>
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/configuration.apt
URL:
http://svn.apache.org/viewcvs/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/configuration.apt?rev=382183&r1=382182&r2=382183&view=diff
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/configuration.apt
(original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/configuration.apt Wed
Mar 1 14:32:57 2006
@@ -72,6 +72,7 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
+ ...
<groups>
<group>
<title>Core Packages</title>
@@ -92,3 +93,32 @@
</project>
-------------------
+*tag
+
+-------------------
+<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>
+-------------------
Modified: maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml
URL:
http://svn.apache.org/viewcvs/maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml?rev=382183&r1=382182&r2=382183&view=diff
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml (original)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/site/site.xml Wed Mar 1
14:32:57 2006
@@ -30,6 +30,7 @@
<body>
<links>
<item name="Maven 2" href="http://maven.apache.org/maven2/"/>
+ <item name="Javadoc Tool" href="http://java.sun.com/j2se/javadoc/"/>
</links>
<menu name="Overview">
Modified:
maven/plugins/trunk/maven-javadoc-plugin/src/test/projects/javadoc-plugin-test1/pom.xml
URL:
http://svn.apache.org/viewcvs/maven/plugins/trunk/maven-javadoc-plugin/src/test/projects/javadoc-plugin-test1/pom.xml?rev=382183&r1=382182&r2=382183&view=diff
==============================================================================
---
maven/plugins/trunk/maven-javadoc-plugin/src/test/projects/javadoc-plugin-test1/pom.xml
(original)
+++
maven/plugins/trunk/maven-javadoc-plugin/src/test/projects/javadoc-plugin-test1/pom.xml
Wed Mar 1 14:32:57 2006
@@ -58,16 +58,32 @@
<source>true</source>
<link>http://java.sun.com/j2se/1.4.2/docs/api,
http://maven.apache.org/apidocs/</link>
<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>
+ <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>
- <tag>.usage:a:Usage:, .todo:a:To do something:, .fixme:a:Fixme:</tag>
+ <tags>
+ <tag>
+ <name>.usage</name>
+ <placement>a</placement>
+ <head>Usage</head>
+ </tag>
+ <tag>
+ <name>.todo</name>
+ <placement>a</placement>
+ <head>To do something:</head>
+ </tag>
+ <tag>
+ <name>.fixme</name>
+ <placement>a</placement>
+ <head>Fixme</head>
+ </tag>
+ </tags>
</configuration>
</plugin>
</plugins>
