javadoc Annotation processing exceptions

gistfile1.txt

If you're seeing 
java.lang.ClassCastException: com.sun.tools.javadoc.ClassDocImpl cannot be cast 
to com.sun.javadoc.AnnotationTypeDoc

the classloader used by the javadoc tool is not finding your 3rd party 
annotation definitions.

This is a problem present in JDK 1.6.

An quick workaround to enable the classloader to find the annotation definitions 
is to add them to the bootclasspath using the -bootclasspath option for javadoc. 

-----
Java language spec, 3rd edition:
    If the JVM is looking for references to another class or interface within 
    a loaded class and determines that the bootstrap class loader didn't 
    already load it, it uses the class loader delegation model for
    the first searches: 
        - it uses the parent classloader to search for the class. If the class 
          was not found using the parent class loader, it uses the class loader.

The hierarchy of class loaders is: 
    - bootstrap classloader is parent,
        - extensions classloader is child
            - system classloader is a child of extensions classloader
                - application specific classloaders are children of the 
                   system classloader.