For debate: documentation annotations

Whenever I work on an API in Java 5 or later, I miss a few annotations that would let me document its basic properties simply, instead of writing them out in Javadoc again and again. Unlike Javadoc text, tools and IDEs could also work with annotations. A classic example is saying that a class is thread safe.

/**
 * Indicates that a class marked this annotation is thread safe.
 */
@Target(ElementType.TYPE)
public @interface ThreadSafe {
}

And its use:

@ThreadSafe
public class Foo {
}

Other annotations would also be useful: for example, one to say that a method parameter is optional (it may be null), or that a class is immutable. I do not know about you, but I think these annotations should be part of Java SE.

Related article

Even more static, on extending the use of annotations (JSR 308: Annotations on Java Types).