Skip to main content

All javadoc tags as annotations

7 replies [Last post]
subanark
Offline
Joined: 2004-11-26
Points: 0

Reply viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.
jwenting
Offline
Joined: 2003-12-02
Points: 0

why not? Because IMO annotations were a bad idea and should never have been put into the language.

I'd instead suggest removing annotations...

denismo
Offline
Joined: 2003-06-28
Points: 0

Javadoc tags should be used for documentation purposes, they don't alter the behavior of the marked entities, they "reveal" it, document some of their aspects.

And annotations should/will be used for everything else. They are "order to action" for some tool, usually not the Javadoc tool, VM etc. They might extend an item, adding a modifier, changing its behavior, its nature, generating something. There is no real use of them for documentation, Javadoc tags should be used instead.

When there were only tags, people used them for many non-documentation purposes, but I think it wasn't the right way, and I believe annotations were created because of the high demand for an extended general-purpose markup, for which Javadoc tags, that are supposed to be used only for documentation, were used.

subanark
Offline
Joined: 2004-11-26
Points: 0

javadoc is a tool just like javac, instead of compiling class files, it compiles documentation. Annotations are used to change how the compiler behaves. Custom annotations are commonly used for custom compilers like ikvm (please no flame).

Next why does the class java.lang.annotation.Documented exist if would only be used for java.lang.Deprecated

And image the advantage that could be bought by allowing tags to determine how they are formatted. E.g.
@Doucmented
@JavaDocStyle("[B]Returns:[/B]\n\t[value]")
public @interface Returns
{
String value();
}

Also see JSR 260

Message was edited by: subanark

patrikbeno
Offline
Joined: 2004-10-11
Points: 0

OK, let me tell you WHY NOT:

- Annotations should be used when they directly or indirectly affect behaviour.
- Comments describe behaviour, they do not affect it (should not). Rule of thumb is that the code should work the same way with or without the comments.

With xdoclet, we abused javadoc comments to do some declarative programming on more or less suitable places. This led to mixed comments - they included both behavioral and non-behavioral stuff.

This is also one of the reasons why annotations were introduced; to decouple things that have to be decoupled.

Besides this, comment as annotation would need to enclose literals in quotes, longer lines would need to be split to multiple literals concatenated using '+' operator.

I think this would be ugly, at least.

vhi
Offline
Joined: 2004-10-11
Points: 0

Problem with such changes are that there would be two ways to do things. One the Old Way and the other the New Way. This makes Java unnecessarily bloated, without any benefit over the current technique.

zander
Offline
Joined: 2003-06-13
Points: 0

annotations end up in compiled classes and more javadoc will mean larger classes and slower iteration over annotations.

Better question; why _would_ you?

subanark
Offline
Joined: 2004-11-26
Points: 0

If the annotation is annotated with:
@Retention(RententionPolicy.SOURCE)
then the compiler doesn't include it in the .class file.

The current way of putting javadoc tags in comments is lazy. With annotations, these tags can be better defined. This was clearly done for Depracated since this tag is compiled in the .class file.