8081820: javadoc does not report warnings in case of multiple "@param" tags for the same parameter and multiple "@return" tags for the same method

Reviewed-by: jjg

langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/Checker.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -821,7 +821,11 @@ public class Checker extends DocTreePathScanner<Void, Void> {
                     break;
             }
         } else {
-            foundParams.add(paramElement);
+            boolean unique = foundParams.add(paramElement);
+
+            if (!unique) {
+                env.messages.warning(REFERENCE, tree, "dc.exists.param", nameTree);
+            }
         }
 
         warnIfEmpty(tree, tree.getDescription());
@@ -870,6 +874,10 @@ public class Checker extends DocTreePathScanner<Void, Void> {
 
     @Override @DefinedBy(Api.COMPILER_TREE)
     public Void visitReturn(ReturnTree tree, Void ignore) {
+        if (foundReturn) {
+            env.messages.warning(REFERENCE, tree, "dc.exists.return");
+        }
+
         Element e = env.trees.getElement(env.currPath);
         if (e.getKind() != ElementKind.METHOD
                 || ((ExecutableElement) e).getReturnType().getKind() == TypeKind.VOID)

langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/resources/doclint.properties

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # This code is free software; you can redistribute it and/or modify it
@@ -39,6 +39,8 @@ dc.bad.value.for.option = bad value for option: {0} {1}
 dc.empty = no description for @{0}
 dc.entity.invalid = invalid entity &{0};
 dc.exception.not.thrown = exception not thrown: {0}
+dc.exists.param = @param "{0}" has already been specified
+dc.exists.return = @return has already been specified
 dc.invalid.anchor = invalid name for anchor: "{0}"
 dc.invalid.param = invalid use of @param
 dc.invalid.provides = invalid use of @provides

langtools/test/tools/doclint/DuplicateParamTest.java

@@ -0,0 +1,24 @@
+/*
+ * @test /nodynamiccopyright/
+ * @bug 8081820
+ * @summary Validate parameter names uniqueness
+ * @modules jdk.compiler/com.sun.tools.doclint
+ * @build DocLintTester
+ * @run main DocLintTester -Xmsgs:-reference DuplicateParamTest.java
+ * @run main DocLintTester -ref DuplicateParamTest.out DuplicateParamTest.java
+ */
+
+/** . */
+public class DuplicateParamTest {
+
+    /**
+     * Test.
+     *
+     * @param s one
+     * @param s two
+     * @param s three
+     *
+     * @return number
+     */
+    public static int Test(String s) { return s.length(); }
+}

langtools/test/tools/doclint/DuplicateParamTest.out

@@ -0,0 +1,7 @@
+DuplicateParamTest.java:18: warning: @param "s" has already been specified
+     * @param s two
+       ^
+DuplicateParamTest.java:19: warning: @param "s" has already been specified
+     * @param s three
+       ^
+2 warnings

langtools/test/tools/doclint/DuplicateReturnTest.java

@@ -0,0 +1,24 @@
+/*
+ * @test /nodynamiccopyright/
+ * @bug 8081820
+ * @summary Validate return uniqueness
+ * @modules jdk.compiler/com.sun.tools.doclint
+ * @build DocLintTester
+ * @run main DocLintTester -Xmsgs:-reference DuplicateReturnTest.java
+ * @run main DocLintTester -ref DuplicateReturnTest.out DuplicateReturnTest.java
+ */
+
+/** . */
+public class DuplicateReturnTest {
+
+    /**
+     * Test.
+     *
+     * @param s one
+     *
+     * @return one
+     * @return two
+     * @return three
+     */
+    public static int Test(String s) { return s.length(); }
+}

langtools/test/tools/doclint/DuplicateReturnTest.out

@@ -0,0 +1,7 @@
+DuplicateReturnTest.java:20: warning: @return has already been specified
+     * @return two
+       ^
+DuplicateReturnTest.java:21: warning: @return has already been specified
+     * @return three
+       ^
+2 warnings