[hibernate-dev] Marking API members as incubating

[Emmanuel Bernard]

On Thu 2013-07-11 14:37, Hardy Ferentschik wrote:
> 
> On 11 Jan 2013, at 12:18 PM, Gunnar Morling <gunnar at hibernate.org> wrote:
> 
> > Here is the thing, we need to also need to start talking retention setting of the annotation.
> > I think you were suggesting source retention. This means that the annotation is only in the
> > source. That means the IDE needs to be linked to the source. I would assume that often
> > developers will setup their IDEs to download sources automatically, but it is not a given.
> > 
> > Yes, you're right. See my response to Sanne's previous message:
> > 
> > > Btw. I got the retention wrong in my first message, it should be CLASS so a user can see whether its present on any API members.
> 
> Ok. I was replying before reading all thread messages.
> What I don't get is how a retention of CLASS works. So it is in the byte code, but does not have to be retained at runtime.
> This means I cannot reflectively determine whether this annotation exists. What's the point in this case? The only way
> to build tooling around this in this case would be to read the actual byte code. Or am I missing something?
> 
> > For the reasons you describe, SOURCE indeed is wrong, but I think CLASS would suffice (that's also what Guava's @Beta uses) which
> > puts it into the class files of types using it. Or is there a need to access the annotation reflectively at runtime?
> 
> See above.
> 
> 
> > Would the aftertaste be gone with using CLASS retention?
> 
> Not unless you explain me how one would actually use such an annotation.

Yes CLASS retention requires to read the bytecode or some higher level
library that read the Java class metamodel.
I am not sure but I suspect that's what IDEs do, they don't load your
class in a CL to read the annotation and list of methods. So the CLASS
retention would be sufficient for an IDE to expose the information to
the user.

One concern about annotations is that there is no standard propagation
level: you cannot say that a constraint on package is thus placed on all
classes in that package. Same for method vs class.
You can define such convention but then you need a specific tool
understanding these conventions.

So annotating a package with @Experimental would not be visible to
someone navigating an API in an IDE (with auto-completion for example).

to be fair JavaDocs have the same problem.

Emmanuel