--override-methods=summary ignores some signature changes

XMLWordPrintable

    • b30
    • generic
    • generic

        A DESCRIPTION OF THE PROBLEM :
        When using javadoc with `--override-methods=summary`, then some changes to the signature of the overriding method are ignored and the method is listed under "Methods declared in".

        Affected changes:
        - Covariant return type: JDK-8219147
        - @Documented annotation on method or its parameters
        - Changed `throws` clause:
          - Added unchecked exception
          - Removed exceptions
        - Changed parameter name (could be intended)

        STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
        1. Create the javadoc for the classes below using `--override-methods=summary`.
        2. Look at the doc for `Sub`

        EXPECTED VERSUS ACTUAL BEHAVIOR :
        EXPECTED -
        The method `doSomething` is listed under "Method Detail" and the user sees the changes to its signature.
        ACTUAL -
        The method `doSomething` is listed under "Methods declared in"; the user does not see any of the changes to its signature.

        ---------- BEGIN SOURCE ----------
        import java.lang.annotation.Documented;

        @Documented
        public @interface MyAnnotation { }

        -----

        public interface Parent {
            /**
             * Method
             *
             * @param a arg
             * @return value
             * @throws Exception never
             */
            Parent doSomething(int a) throws Exception;
        }

        -----

        public interface Sub extends Parent {
            /*
             * Changes:
             * - Return type
             * - Used @Documented annotation:
             * - Method
             * - Parameter
             * - `throws` clause:
             * - Not throwing `Exception`
             * - Throwing `IllegalArgumentException`
             * - Parameter name (could be intended that change is ignored)
             */
            @Override
            @MyAnnotation
            Sub doSomething(@MyAnnotation int aNewName) throws IllegalArgumentException;
        }
        ---------- END SOURCE ----------


        It appears this also affects changes to the visibility:
        public class A {
            /**
             * Does something
             */
            protected void doSomething() { }
        }

        public class B {
            @Override
            public void doSomething() { }
        }

        -----

        The documentation for B does not show "doSomething" under "Method Detail" so the user does not know it is public.

          1. MyAnnotation.java
            0.1 kB
          2. Parent.java
            0.2 kB
          3. Sub.java
            0.5 kB

              Assignee:
              Hannes Wallnoefer
              Reporter:
              Webbug Group
              Votes:
              0 Vote for this issue
              Watchers:
              7 Start watching this issue

                Created:
                Updated:
                Resolved: