This is an automated email from the ASF dual-hosted git repository.
rfscholte pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-javadoc-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new 5bb92b7 [MJAVADOC-452] Support duplicate @param entries
5bb92b7 is described below
commit 5bb92b7b4b826d1fd797d5465a84b1fbeb8a6601
Author: rfscholte <rfscho...@apache.org>
AuthorDate: Sat Dec 29 12:04:48 2018 +0100
[MJAVADOC-452] Support duplicate @param entries
---
.../invoker.properties | 18 ++++++
.../MJAVADOC-452_fix-duplicateparams/pom.xml | 70 ++++++++++++++++++++++
.../src/main/java/com/example/FirstBug.java | 36 +++++++++++
.../MJAVADOC-452_fix-duplicateparams/verify.groovy | 26 ++++++++
.../plugins/javadoc/AbstractFixJavadocMojo.java | 61 +++++++++----------
5 files changed, 181 insertions(+), 30 deletions(-)
diff --git
a/src/it/projects/MJAVADOC-452_fix-duplicateparams/invoker.properties
b/src/it/projects/MJAVADOC-452_fix-duplicateparams/invoker.properties
new file mode 100644
index 0000000..2f27cf0
--- /dev/null
+++ b/src/it/projects/MJAVADOC-452_fix-duplicateparams/invoker.properties
@@ -0,0 +1,18 @@
+# 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.
+
+invoker.goals=javadoc:fix compile javadoc:javadoc
diff --git a/src/it/projects/MJAVADOC-452_fix-duplicateparams/pom.xml
b/src/it/projects/MJAVADOC-452_fix-duplicateparams/pom.xml
new file mode 100644
index 0000000..5060507
--- /dev/null
+++ b/src/it/projects/MJAVADOC-452_fix-duplicateparams/pom.xml
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ 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.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd";>
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.apache.maven.plugins.maven-javadoc-plugin.it</groupId>
+ <artifactId>mjavadoc452</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
+
+ <url>https://issues.apache.org/jira/browse/MJAVADOC-452</url>
+
+ <build>
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>@project.version@</version>
+ <configuration>
+ <force>true</force>
+ <ignoreClirr>true</ignoreClirr>
+ </configuration>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+ </build>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.springframework</groupId>
+ <artifactId>spring-context</artifactId>
+ <version>3.2.2.RELEASE</version>
+ </dependency>
+ <dependency>
+ <groupId>org.springframework</groupId>
+ <artifactId>spring-webmvc</artifactId>
+ <version>3.2.2.RELEASE</version>
+ </dependency>
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-api</artifactId>
+ <version>1.7.5</version>
+ </dependency>
+ <dependency>
+ <groupId>javax.servlet</groupId>
+ <artifactId>servlet-api</artifactId>
+ <scope>provided</scope>
+ <version>2.5</version>
+ </dependency>
+ </dependencies>
+</project>
diff --git
a/src/it/projects/MJAVADOC-452_fix-duplicateparams/src/main/java/com/example/FirstBug.java
b/src/it/projects/MJAVADOC-452_fix-duplicateparams/src/main/java/com/example/FirstBug.java
new file mode 100644
index 0000000..b6586cc
--- /dev/null
+++
b/src/it/projects/MJAVADOC-452_fix-duplicateparams/src/main/java/com/example/FirstBug.java
@@ -0,0 +1,36 @@
+package com.example;
+
+/*
+ * 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.
+ */
+
+/**
+ * <p>FirstBug class.</p>
+ */
+public class FirstBug {
+
+ /**
+ * <p>mymethod.</p>
+ *
+ * @param param first param
+ * @param param copy-paste mistake of first param
+ */
+ public void mymethod( String param, String paramSecond ) {
+
+ }
+}
\ No newline at end of file
diff --git a/src/it/projects/MJAVADOC-452_fix-duplicateparams/verify.groovy
b/src/it/projects/MJAVADOC-452_fix-duplicateparams/verify.groovy
new file mode 100644
index 0000000..8a9599a
--- /dev/null
+++ b/src/it/projects/MJAVADOC-452_fix-duplicateparams/verify.groovy
@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+
+def file = new File( basedir, 'src/main/java/com/example/FirstBug.java' );
+
+assert file.exists()
+
+// having the same @param mentioned twice is allowed, ensure it stays this way.
+assert 1 == file.text.count('* @param param first param')
+assert 1 == file.text.count('* @param param copy-paste mistake of first param')
diff --git
a/src/main/java/org/apache/maven/plugins/javadoc/AbstractFixJavadocMojo.java
b/src/main/java/org/apache/maven/plugins/javadoc/AbstractFixJavadocMojo.java
index f8fac33..3d7e7b7 100644
--- a/src/main/java/org/apache/maven/plugins/javadoc/AbstractFixJavadocMojo.java
+++ b/src/main/java/org/apache/maven/plugins/javadoc/AbstractFixJavadocMojo.java
@@ -74,6 +74,7 @@ import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
+import java.util.HashSet;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.LinkedList;
@@ -81,6 +82,7 @@ import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Properties;
+import java.util.Set;
import java.util.StringTokenizer;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
@@ -1958,7 +1960,7 @@ public abstract class AbstractFixJavadocMojo
switch ( docletTag.getName() )
{
case PARAM_TAG:
- javaEntityTags.putJavadocParamTag( paramName,
originalJavadocTag );
+ javaEntityTags.putJavadocParamTag( paramName,
docletTag.getValue(), originalJavadocTag );
break;
case RETURN_TAG:
javaEntityTags.setJavadocReturnTag( originalJavadocTag
);
@@ -2005,7 +2007,7 @@ public abstract class AbstractFixJavadocMojo
if ( docletTag.getName().equals( PARAM_TAG ) )
{
- writeParamTag( sb, javaExecutable, javaEntityTags, params
);
+ writeParamTag( sb, javaExecutable, javaEntityTags,
params.get( 0 ), docletTag.getValue() );
}
else if ( docletTag.getName().equals( RETURN_TAG ) &&
javaExecutable instanceof JavaMethod )
{
@@ -2058,14 +2060,12 @@ public abstract class AbstractFixJavadocMojo
}
private void writeParamTag( final StringBuilder sb, final JavaExecutable
javaExecutable,
- final JavaEntityTags javaEntityTags,
List<String> params )
+ final JavaEntityTags javaEntityTags, String
paramName, String paramValue )
{
- String paramName = params.get( 0 );
-
if ( !fixTag( PARAM_TAG ) )
{
// write original param tag if found
- String originalJavadocTag = javaEntityTags.getJavadocParamTag(
paramName );
+ String originalJavadocTag = javaEntityTags.getJavadocParamTag(
paramValue );
if ( originalJavadocTag != null )
{
sb.append( originalJavadocTag );
@@ -2107,7 +2107,7 @@ public abstract class AbstractFixJavadocMojo
}
else
{
- String originalJavadocTag = javaEntityTags.getJavadocParamTag(
paramName );
+ String originalJavadocTag = javaEntityTags.getJavadocParamTag(
paramValue );
if ( originalJavadocTag != null )
{
sb.append( originalJavadocTag );
@@ -2258,7 +2258,7 @@ public abstract class AbstractFixJavadocMojo
{
for ( JavaParameter javaParameter :
javaExecutable.getParameters() )
{
- if ( javaEntityTags.getJavadocParamTag(
javaParameter.getName(), true ) == null )
+ if ( !javaEntityTags.hasJavadocParamTag(
javaParameter.getName() ) )
{
appendDefaultParamTag( sb, indent, javaParameter );
}
@@ -2269,7 +2269,7 @@ public abstract class AbstractFixJavadocMojo
{
for ( JavaTypeVariable<JavaGenericDeclaration> typeParam :
javaExecutable.getTypeParameters() )
{
- if ( javaEntityTags.getJavadocParamTag( "<" +
typeParam.getName() + ">", true ) == null )
+ if ( !javaEntityTags.hasJavadocParamTag( "<" +
typeParam.getName() + ">" ) )
{
appendDefaultParamTag( sb, indent, typeParam );
}
@@ -3302,20 +3302,19 @@ public abstract class AbstractFixJavadocMojo
String originalJavadoc = extractOriginalJavadocContent(
javaClassContent, entity );
- List<String> params = docletTag.getParameters();
- String paramValue = params.get( 0 );
-
StringBuilder sb = new StringBuilder();
BufferedReader lr = new BufferedReader( new StringReader(
originalJavadoc ) );
String line;
boolean found = false;
+
+ // matching first line of doclettag
+ Pattern p = Pattern.compile( "(\\s*\\*\\s?@" + docletTag.getName() +
")\\s+"
+ + "(\\Q" + docletTag.getValue().split( "\r\n|\r|\n" )[0] + "\\E)"
);
+
while ( ( line = lr.readLine() ) != null )
{
- String l = StringUtils.removeDuplicateWhitespace( line.trim() );
- if ( l.startsWith( "* @" + docletTag.getName() + " " + paramValue
+ " " )
- || l.startsWith( "*@" + docletTag.getName() + " " + paramValue
+ " " )
- || l.equals( "* @" + docletTag.getName() + " " + paramValue )
- || l.equals( "*@" + docletTag.getName() + " " + paramValue ) )
+ Matcher m = p.matcher( line );
+ if ( m.matches() )
{
if ( fixTag( LINK_TAG ) )
{
@@ -3326,7 +3325,7 @@ public abstract class AbstractFixJavadocMojo
}
else
{
- if ( l.startsWith( "* @" ) || l.startsWith( "*@" ) )
+ if ( line.trim().startsWith( "* @" ) ||
line.trim().startsWith( "*@" ) )
{
found = false;
}
@@ -3668,6 +3667,8 @@ public abstract class AbstractFixJavadocMojo
* Map with java parameter as key and original Javadoc lines as values.
*/
private Map<String, String> tagParams;
+
+ private Set<String> documentedParams = new HashSet<>();
/**
* Original javadoc lines.
@@ -3714,27 +3715,27 @@ public abstract class AbstractFixJavadocMojo
return unknownsTags;
}
- public void putJavadocParamTag( String paramName, String
originalJavadocTag )
- {
- tagParams.put( paramName, originalJavadocTag );
- }
-
- public String getJavadocParamTag( String paramName )
+ public void putJavadocParamTag( String paramName, String paramValue,
String originalJavadocTag )
{
- return getJavadocParamTag( paramName, false );
+ documentedParams.add( paramName );
+ tagParams.put( paramValue, originalJavadocTag );
}
- public String getJavadocParamTag( String paramName, boolean nullable )
+ public String getJavadocParamTag( String paramValue )
{
- String originalJavadocTag = tagParams.get( paramName );
- if ( !nullable && originalJavadocTag == null &&
getLog().isWarnEnabled() )
+ String originalJavadocTag = tagParams.get( paramValue );
+ if ( originalJavadocTag == null && getLog().isWarnEnabled() )
{
- getLog().warn( getMessage( paramName,
"javaEntityTags.tagParams" ) );
+ getLog().warn( getMessage( paramValue,
"javaEntityTags.tagParams" ) );
}
-
return originalJavadocTag;
}
+ public boolean hasJavadocParamTag( String paramName )
+ {
+ return documentedParams.contains( paramName );
+ }
+
public void putJavadocThrowsTag( String paramName, String
originalJavadocTag )
{
tagThrows.put( paramName, originalJavadocTag );
