Improved documentation for MethodParameter#getAnnotatedElement

[chrylis]

Affects: 5.3.27

The Javadoc for MethodParameter#getAnnotatedElement() reads Return the wrapped annotated element. Presumably for legacy reasons (since Parameter was added only in Java 8), this method returns the Method object for the method on which the MethodParameter resides rather than the Parameter object representing the parameter itself. This behavior is surprising; I expected the Parameter to be returned. Instead, to do this it seems I use #getParameter()

Since this API is widely used, altering the behavior is probably impractical. Instead, I suggest replacing the Javadoc on #getAnnotatedElement() to read:

Return the method or constructor on which this parameter resides. For the {@link AnnotatedElement} for this parameter itself, use {@link #getParameter()}.

[snicoll]

The Javadoc reads as follow:

Return the wrapped annotated element.
Note: This method exposes the annotations declared on the method/constructor itself (i.e. at the method/constructor level, not at the parameter level).
Returns: the Method or Constructor as AnnotatedElement

The note makes it pretty obvious what it does already, but the reference to #getParameter is helpful indeed.