This function finds an annotation with the specified qualified name assigned
to the specified package, program element or constructor/method's parameter
(or an element of that kind to which the specified element
immediately leads; see element
parameter for details).
If the annotation is found the function returns it.
If the annotation is not found and the initial element is
a program element (that is an instance of
com.sun.javadoc.ProgramElementDoc
interface,
which represents a Java class or a class member),
the search is continued in the class containing that program element.
This will repeat until the annotation is found or a top (non-inner) class is reached.
This function may be particularly useful when some annotations specified in a class affect processing of the class' members and its inner classes.
For instance, when for a given method you need to know if either the method itself or the class containing it has a certain annotation, you may test it using the following expression:
Note, since only checking the annotation presence (not the annotation itself) is needed in the most cases, for better performance, the function returns the element identifier (seemethod.findAnnotation( "project.util.MyAnnotation") != null
GOMElement.id
)
of the found annotation (not an AnnotationDesc
element representing it).
To convert the identifier to the element,
you should use findElementById()
function:
Parameters:findElementById ( findAnnotation("project.util.MyAnnotation") )
element
ThePackageDoc
,ProgramElementDoc
orParameter
element whose annotation is requested.The parameter may be also:
If the
- A
Type
element, which is automatically converted to theClassDoc
by calling the Doclet API method:Type.asClassDoc()
- An
AnnotationDesc
element, which is automatically converted to theAnnotationTypeDoc
by calling the Doclet API method:AnnotationTypeDoc.annotationType()
element
is not an instance of one of those types, the function returnsnull
.If this parameter is not specified, the generator context element is assumed, i.e. the same as the call:
contextElement.findAnnotation(qualifiedName)
qualifiedName
The fully qualified name of the annotation type to search for.
qualifiedNames
Instead of a single name, you may specify several fully qualified names in the form of an array (e.g. created withReturns:Array()
function). For example:In that case, the function will search for an annotation with the first type name specified in the array, then, if not found, for an annotation with the second type name and so on.findAnnotation ( Array ( "project.util.Annotation1", "project.util.Annotation2" ) )
The element identifier of the found annotation orSee Also:null
if no annotation found.To convert the returned identifier to the
AnnotationDesc
element (representing the found annotation), please usefindElementById()
function.
hasAnnotation(), getAnnotation(), GOMElement.id, findElementById()