[hibernate-dev] Marking API members as incubating

[Gunnar Morling]

2013/7/11 Hardy Ferentschik <hardy at hibernate.org>

>
> On 11 Jan 2013, at 12:30 PM, Gunnar Morling <gunnar at 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