improve extension API documentation and resolve some open questions #515
Conversation
|
Hey @Ladicek currently on vacation until 30th of August. Will review when I get back! |
|
Sure, no worries, and enjoy! :-) |
api/src/main/java/jakarta/enterprise/lang/model/AnnotationInfo.java
Outdated
Show resolved
Hide resolved
- renamed/moved `AnnotationInfo.MEMBER_VALUE` to `AnnotationMember.VALUE` - replaced the phrase "component type" with "element type" when speaking about arrays, because JLS uses both and each has a different meaning - removed `ContextConfig`, custom context registration is now fully handled in `MetaAnnotations` - removed unnecessarily concrete language from `@SkipIfPortableExtensionPresent` - methods in the `Types` class now have more specific return types - implementations of `AnnotationInfo`, `AnnotationMember` and `AnnotationTarget` are now required to define `equals` and `hashCode`, and are explicitly not required to use a single object to represent a single construct - the `ClassInfo` declaration is now required to return annotations `@Inherited` from a superclass, per `@Inherited` spec and CDI spec - explicitly documented that `ClassInfo` doesn't provide access to nested classes or an enclosing class, and `PackageInfo` doesn't provide access to package members - corrected some language to distinguish between generic classes (before type argument application) and parameterized types (after type argument application) - specified meaning of `MethodInfo.name` and `returnType` for constructors, mirroring what reflection does (returning the declaring class) - defined how implicit bounds are represented in `TypeVariable` and `WildcardType` - removed `ObserverInfo.id()` - usage of `Optional` was eliminated everywhere - instead of "`void` type", we now always use "`void` pseudo-type" - added `@since 4.0` tags everywhere - changed `@link` tags to `@linkplain` if the link text isn't an identifier
c0ecb24 to
2d14e87
Compare
| * @throws IllegalArgumentException if the {@code scopeAnnotation} isn't meta-annotated {@code @NormalScope} | ||
| * or {@code @Scope} | ||
| */ | ||
| void addContext(Class<? extends Annotation> scopeAnnotation, Class<? extends AlterableContext> contextClass); |
There was a problem hiding this comment.
Can we add variants that take a ClassInfo for contextClass since this is likely to be part of the implementation
There was a problem hiding this comment.
At this point (@Discovery), there's no way how to obtain a ClassInfo.
There was a problem hiding this comment.
All I can think of is we can change that parameter to String, if Class is bad.
| // to the numeric primitive types and maybe String. I currently left the numeric | ||
| // as* methods documented as coercing, while asString as not coercing, but this | ||
| // needs more discussion. I personally don't like coercion here and would always | ||
| // throw if the type mismatches. |
There was a problem hiding this comment.
Seems it is a slippery slope and just disallowing coercion may be easier to reason about. Having said that my current implementation is doing coercion
There was a problem hiding this comment.
I'd prefer disallowing coercion, but again, I can be convinced otherwise :-)
|
|
||
| // TODO what about constructors? | ||
| /** | ||
| * Returns the name of this method. In case of constructors, returns the binary name of the declaring class. |
There was a problem hiding this comment.
Should it not return <init> for constructors?
There was a problem hiding this comment.
It could do both. I thought class name would be better, as that's what reflection does, but I can be convinced otherwise.
|
Thanks! |
AnnotationInfo.MEMBER_VALUEtoAnnotationMember.VALUEabout arrays, because JLS uses both and each has a different meaning
ContextConfig, custom context registration is now fullyhandled in
MetaAnnotations@SkipIfPortableExtensionPresentTypesclass now have more specific return typesAnnotationInfo,AnnotationMemberandAnnotationTargetare now required to define
equalsandhashCode, and are explicitlynot required to use a single object to represent a single construct
ClassInfodeclaration is now required to return annotations@Inheritedfrom a superclass, per@Inheritedspec and CDI specClassInfodoesn't provide access to nestedclasses or an enclosing class, and
PackageInfodoesn't provide accessto package members
type argument application) and parameterized types (after type argument
application)
MethodInfo.nameandreturnTypefor constructors,mirroring what reflection does (returning the declaring class)
TypeVariableand
WildcardTypeObserverInfo.id()Optionalwas eliminated everywherevoidtype", we now always use "voidpseudo-type"@since 4.0tags everywhere@linktags to@linkplainif the link text isn't an identifier