Annotations
| Topics: |
| Navigate Javadoc & Annotations topic: |
Javadoc is the Java source code document generator and was introduced with the Java language from version 1.0 .
Well commented Java code is supposed to have Javadoc tags. Those tags are in the /** ... */ comment blocks, so the compiler ignores them. A separate utility would read the code and create the Java API html files.
The Javadoc API documentations are well known. The Java JDK classes are coming with Javadoc API documentations. Most popular IDE tools automatically read Javadoc tags and wherever that class, attribute or method are used, the tags content are displayed automatically, when the mouse cursor is over the text.
As Java matured, the "Javadoc concept" was recognized as an excellent tool for other purposes, like generating XML descriptors, or even generating Java code, with the help of the XDoclet open source program.
With the help of the XDoclet program, it was possible to use additional Javadoc tags in the code that this program would understand and generate code or data. For example, Javadoc tags were introduced to generate XML descriptors for EJBs. It introduced an additional step in the build process of an EJB, and compiling the code XDoclet would generate the XML descriptors.
Recognizing its usefulness, in Java 5, annotation was added to the Java language. Annotation tags are NOT inside a comment block. An annotation is part of the class and it may be accessed at runtime.
Wherever XML descriptors were heavily used, now an alternative way is available that is the Java annotation. From EJB 3.0, it is possible to define EJBs without using XML. Also the new JPA (Java Persistent API) uses annotations.
It is important to note, that Javadoc and annotation are two different constructs.
- Javadoc tags are inside a comment block and as such ignored by the compiler.
- Annotation tags are outside of comment blocks and they are type checked by the compiler.