Comment by dibbeke

Agreed, they aren't the prettiest thing in Java and they only allow one 'layer' of annotating (you can't use expressions in annotations for example), they do prove it is possible to document your code in Java in a way that it becomes part of the 'environment' (again, 'environment' is ill-defined, so all arguments in this line are a bit frail).