25
25
26
26
package jdk .javadoc .internal .doclets .toolkit .util ;
27
27
28
+ import javax .lang .model .element .AnnotationMirror ;
28
29
import javax .lang .model .element .Element ;
29
30
import javax .lang .model .element .ExecutableElement ;
31
+ import javax .lang .model .element .Modifier ;
30
32
import javax .lang .model .element .TypeElement ;
31
33
import javax .lang .model .element .VariableElement ;
34
+ import javax .lang .model .type .ArrayType ;
35
+ import javax .lang .model .type .DeclaredType ;
36
+ import javax .lang .model .type .ExecutableType ;
32
37
import javax .lang .model .type .TypeKind ;
33
38
import javax .lang .model .type .TypeMirror ;
39
+ import javax .lang .model .type .WildcardType ;
34
40
import javax .lang .model .util .Elements ;
35
41
import javax .lang .model .util .SimpleElementVisitor14 ;
42
+ import javax .lang .model .util .SimpleTypeVisitor14 ;
36
43
import java .lang .ref .SoftReference ;
37
44
import java .util .ArrayList ;
38
45
import java .util .Collections ;
39
46
import java .util .EnumMap ;
40
47
import java .util .EnumSet ;
41
48
import java .util .HashMap ;
49
+ import java .util .HashSet ;
42
50
import java .util .LinkedHashMap ;
43
51
import java .util .LinkedHashSet ;
44
52
import java .util .List ;
@@ -582,14 +590,10 @@ boolean allowInheritedMethods(ExecutableElement inheritedMethod,
582
590
return false ;
583
591
}
584
592
585
- TypeMirror inheritedMethodReturn = inheritedMethod .getReturnType ();
586
- TypeMirror lMethodReturn = lMethod .getReturnType ();
587
- boolean covariantReturn =
588
- lMethodReturn .getKind () == TypeKind .DECLARED
589
- && inheritedMethodReturn .getKind () == TypeKind .DECLARED
590
- && !utils .typeUtils .isSameType (lMethodReturn , inheritedMethodReturn )
591
- && utils .typeUtils .isSubtype (lMethodReturn , inheritedMethodReturn );
592
- boolean simpleOverride = covariantReturn ? false : utils .isSimpleOverride (lMethod );
593
+ // Even with --override-methods=summary we want to include details of
594
+ // overriding method if something noteworthy has been added or changed.
595
+ boolean simpleOverride = utils .isSimpleOverride (lMethod )
596
+ && !overridingSignatureChanged (lMethod , inheritedMethod );
593
597
overriddenMethodTable .computeIfAbsent (lMethod ,
594
598
l -> new OverridingMethodInfo (inheritedMethod , simpleOverride ));
595
599
return simpleOverride ;
@@ -598,6 +602,90 @@ boolean allowInheritedMethods(ExecutableElement inheritedMethod,
598
602
return true ;
599
603
}
600
604
605
+ // Check whether the signature of an overriding method has any changes worth
606
+ // being documented compared to the overridden method.
607
+ private boolean overridingSignatureChanged (ExecutableElement method , ExecutableElement overriddenMethod ) {
608
+ // Covariant return type
609
+ TypeMirror overriddenMethodReturn = overriddenMethod .getReturnType ();
610
+ TypeMirror methodReturn = method .getReturnType ();
611
+ if (methodReturn .getKind () == TypeKind .DECLARED
612
+ && overriddenMethodReturn .getKind () == TypeKind .DECLARED
613
+ && !utils .typeUtils .isSameType (methodReturn , overriddenMethodReturn )
614
+ && utils .typeUtils .isSubtype (methodReturn , overriddenMethodReturn )) {
615
+ return true ;
616
+ }
617
+ // Modifiers changed from protected to public, non-final to final, or change in abstractness
618
+ Set <Modifier > modifiers = method .getModifiers ();
619
+ Set <Modifier > overriddenModifiers = overriddenMethod .getModifiers ();
620
+ if ((modifiers .contains (Modifier .PUBLIC ) && overriddenModifiers .contains (Modifier .PROTECTED ))
621
+ || modifiers .contains (Modifier .FINAL )
622
+ || modifiers .contains (Modifier .ABSTRACT ) != overriddenModifiers .contains (Modifier .ABSTRACT )) {
623
+ return true ;
624
+ }
625
+ // Change in thrown types
626
+ if (!method .getThrownTypes ().equals (overriddenMethod .getThrownTypes ())) {
627
+ return true ;
628
+ }
629
+ // Documented annotations added anywhere in the method signature
630
+ return !getDocumentedAnnotations (method ).equals (getDocumentedAnnotations (overriddenMethod ));
631
+ }
632
+
633
+ private Set <AnnotationMirror > getDocumentedAnnotations (ExecutableElement element ) {
634
+ Set <AnnotationMirror > annotations = new HashSet <>();
635
+ addDocumentedAnnotations (annotations , element .getAnnotationMirrors ());
636
+
637
+ new SimpleTypeVisitor14 <Void , Void >() {
638
+ @ Override
639
+ protected Void defaultAction (TypeMirror e , Void v ) {
640
+ addDocumentedAnnotations (annotations , e .getAnnotationMirrors ());
641
+ return null ;
642
+ }
643
+
644
+ @ Override
645
+ public Void visitArray (ArrayType t , Void unused ) {
646
+ if (t .getComponentType () != null ) {
647
+ visit (t .getComponentType ());
648
+ }
649
+ return super .visitArray (t , unused );
650
+ }
651
+
652
+ @ Override
653
+ public Void visitDeclared (DeclaredType t , Void unused ) {
654
+ t .getTypeArguments ().forEach (this ::visit );
655
+ return super .visitDeclared (t , unused );
656
+ }
657
+
658
+ @ Override
659
+ public Void visitWildcard (WildcardType t , Void unused ) {
660
+ if (t .getExtendsBound () != null ) {
661
+ visit (t .getExtendsBound ());
662
+ }
663
+ if (t .getSuperBound () != null ) {
664
+ visit (t .getSuperBound ());
665
+ }
666
+ return super .visitWildcard (t , unused );
667
+ }
668
+
669
+ @ Override
670
+ public Void visitExecutable (ExecutableType t , Void unused ) {
671
+ t .getParameterTypes ().forEach (this ::visit );
672
+ t .getTypeVariables ().forEach (this ::visit );
673
+ visit (t .getReturnType ());
674
+ return super .visitExecutable (t , unused );
675
+ }
676
+ }.visit (element .asType ());
677
+
678
+ return annotations ;
679
+ }
680
+
681
+ private void addDocumentedAnnotations (Set <AnnotationMirror > annotations , List <? extends AnnotationMirror > annotationMirrors ) {
682
+ annotationMirrors .forEach (annotation -> {
683
+ if (utils .isDocumentedAnnotation ((TypeElement ) annotation .getAnnotationType ().asElement ())) {
684
+ annotations .add (annotation );
685
+ }
686
+ });
687
+ }
688
+
601
689
/*
602
690
* This class encapsulates the details of local members, orderedMembers
603
691
* contains the members in the declaration order, additionally a
0 commit comments