Custom annotations instead of custom doc tags

[trajano]

Rather than javadoc doc tags, perhaps use custom annotations (since you're targetting JDK5+ anyway) that way we won't get warnings that the tag is unknown in javadoc and we can make it type safe.

[dspinellis]

Nice idea, thanks! This will however break backward compatibility. How do you suggest to address this problem?

[trajano]

There's no need to break backward compatibility. The annotations are add-ons.
Basically you have the following as equivalent

/**
 * @opt foo
 * @opt bar
 */
public class Mine

/**
 * @opt foo
 */
@UmlGraph.Bar
public class Mine

/**
 * 
 */
@UmlGraph.Foo
@UmlGraph.Bar
public class Mine

[dspinellis]

OK, I see, so we should support both. Makes sense, thank you!

[kno10]

I had been considering to propose this.

There is a problem with this approach:

• source retention annotations are supposedly not available when building the JavaDoc, and cannot be accessed via introspection
• runtime accessible annotation - that would be accessible - make class files larger, and waste some memory in the VM

This would work much better when actually parsing the java sources with, e.g., the javaparser module. But at some point this means completely rewriting JavaDoc itself to a substantial extend...
Also, this may have changed with Java 9+ when JavaDoc was rewritten (and broke the UMLGraph doclet...). But when relying on accessing the non-retained annotations via the JavaDoc document, this will A) not work in the non-javadoc mode, and B) get us further exactly into this tight javadoc version dependency that just broke the integration...

[trajano]

We can do it a hacky way by making it update the source to put in the "@opt" tags in the generated javadoc. However, this will not help with JDK9+. The problem with JDK9+ is they locked down Standard Doclet/HtmlDoclet so we can't just inject our own HTML along theirs. (Unless you guys found a way around it, I tried and failed for the moment)

[trajano]

Mind you the way UMLGraph has it now with UMLOptions adds code for the VM as well.

[trajano]

@kno10 can CLASS retention be usable for JavaDoc? Class retention makes the class size bigger but the data is not available in runtime so the VM memory shouldn't be impacted as much.

[kno10]

A class such as UMLOptions will not be loaded into the VM unless you use it somewhere (but I would also prefer using the package-info, but this may be much harder to access). It should be easy to omit it from the jar altogether.
I don't think CLASS works, unless you want to load the classes yourself with bytecode inspection. Which makes things even worse, because you don't have the javadoc there anymore. Javaparser or eclipses parser are probably the only things that gives you access to both the non-runtime annotations as well as the javadoc comments. Unfortunately, javaparser does not parse the comments for you. Maybe some Eclipse code (JavaDoc2HTMLTextReader) could be repurposed for this.
AFAIK the VM will skip CLASS retention entries when loading the class, so you can't access it by introspection in javadoc; you need to read the bytecode yourself.
Probably the best way is by now to ditch Oracles javadoc and move on to something that also supports Markdown syntax, MathJax, Asciidoc or similar styles for code documentation...

[kno10]

A common approach for extending javadoc HTML always was to wait until the standard doclet has done its job, then 'edit' the generated HTML and insert your extensions. :-( But of course that breaks every other JDK version. its really an anti-API what Oracle does with javadoc...

[ekaratarakis]

So this idea suggests that the custommade tags should coexist with the javadoc tags, right? Please correct me if Im wrong,

[trajano]

@ekaratarakis almost (I am talking about custom annotations not tags)

I don't want to break compatibility by adding support for the Java Annotations that are UMLGraph specific.

[ekaratarakis]

Right I see. So apart from avoiding the warnings that the tag is unknown in javadoc, would you suggest any another benefit in using custom annotations?

[kno10]

Annotations have a clear API and a much less fragile. Javadoc tags can break when e.g. code formatting adds a line break.
If we had an annotation such as @has(Object.class) rather than @has("Object") then this can also automatically be refactored. JavaDoc tags usually won't be updated by Eclipse, for example.