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

--override-methods=summary ignores some signature changes

    XMLWordPrintable

Details

    • b30
    • generic
    • generic

    Backports

      Description

        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.

        Attachments

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

          Issue Links

            Activity

              People

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

                Dates

                  Created:
                  Updated:
                  Resolved: