2013/7/11 Hardy Ferentschik <hardy(a)hibernate.org>
On 11 Jan 2013, at 12:30 PM, Gunnar Morling <gunnar(a)hibernate.org> wrote:
> I think hovering over a method I want to use in my IDE and seeing it is
annotated with @Incubating gives me that information much faster than going
to a wiki or online docs.
would you get that out of the box?
I only know about Eclipse; There you see by default the declared
annotations when hovering with the mouse over a method. Of course it's the
same with JavaDoc if you have downloaded it.
> The latter also doesn't give me the possibility for
tool-based access to
this information.
Yes in theory, but honestly do you really expect someone is building such
a tool? Maybe if this
@Experimental/@Incubating annotation would be some sort of standard, but
building a tool
to discover incubating features of let's say Hibernate Validator seems
over the top.
I could envision a more generic tool which is configurable with the
annotations to watch for. Similar to Eclipse which has a nullability check
based on a configurable custom @NonNull annotation.
> Are there any specific issues you see about using an annotation?
I am not per se against it. I am just trying to fully understand how it
would look like (aka
retention, etc). For now the only convincing argument for me for such an
annotation would be
the generation of the "Use" javadocs. For that a SOURCE level retention
would be sufficient.
The tooling argument I find not very convincing and is imo only practical
in case of a RUNTIME
retention.
It could be RUNTIME, but I think a user wouldn't check for references to
incubating APIs at the runtime of her application but more likely at
development/build time. For that purpose CLASS would suffice. Using SOURCE
would cause the annotation not to show up in the user's IDE, so I think it
should be one of the other two retention levels.
--Hardy