Recently I had to prepare a presentation on Java Annotations and went right to the source: Sun’s documentation.

I was able to find only these two pages on annotation. To say the least, such poor explanation of a new language feature is not sufficient for the vast majority of Java developers.

But things get much worse if you’ll try to understand what is the “Annotation processing tool”. Just open Sun’s

“Getting Started with APT”. It starts as follows (remember, this is a Getting Started manual):

“The command-line utility apt, annotation processing tool, finds and executes annotation processors based

on the annotations present in the set of specified source files being examined. The annotation processors

use a set of reflective APIs and supporting infrastructure to perform their processing of program annotations (JSR 175).”

I have a feeling the manager of the technical writer who wrote this piece of crap gave him the following assignment:

“You know Joe, I do not like apt, and it was a bad decision to even include this tool in J2SE 5.0.

Write the Getting Started manual on apt, but make sure that people will hate this tool and will never use it”…

After writing this manual Joe got unusually large bonus.

I admire Sun’s Java evangelists traveling around the globe explaining the new language

features, but why their documentation is sub-standard? They just do not want to invest into this area knowing

that there are millions of Java enthusiasts (I’m being one of them) who will write about each

and every feature of the language anyway.

Meanwhile, I was able to prepare a presentation and some simple and practical samples that will help

my students in understanding of this nice feature. One day I’ll write an article on annotations.

I won’t sit by the phone waiting for a phone call from Sun, but I’ll keep writing about this

language… until a better one is created.