Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8223607

--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

              hannesw Hannes Wallnoefer
              webbuggrp Webbug Group
              Votes:
              0 Vote for this issue
              Watchers:
              7 Start watching this issue

                Created:
                Updated:
                Resolved: