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:


method.findAnnotation(
  "project.util.MyAnnotation") != null
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 (see GOMElement.id) of the found annotation (not an AnnotationDesc element representing it). To convert the identifier to the element, you should use findElementById() function:

findElementById (
  findAnnotation("project.util.MyAnnotation")
)
Parameters:

element

The PackageDoc, ProgramElementDoc or Parameter element whose annotation is requested.

The parameter may be also:

If the element is not an instance of one of those types, the function returns null.

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 with Array() function). For example:
findAnnotation (
  Array (
    "project.util.Annotation1", 
    "project.util.Annotation2"
  )
)
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.
Returns:
The element identifier of the found annotation or null if no annotation found.

To convert the returned identifier to the AnnotationDesc element (representing the found annotation), please use findElementById() function.

See Also:
hasAnnotation(), getAnnotation(), GOMElement.id, findElementById()