[hibernate-dev] Marking API members as incubating

[Hardy Ferentschik]

On 10 Jan 2013, at 5:48 PM, Gunnar Morling <gunnar at hibernate.org> wrote:

> So basically we're looking for a way to inform the user and say "it's ok to
> use this API, but be prepared to changes in the future". One way to do this
> is documentation, i.e. prose or a custom JavaDoc tag such as @experimental.
> This has been done in HSEARCH before.

I think that is the easiest. IMO that is sufficient. 

> Alternatively a Java 5 annotation could be used which I'd personally find
> advantageous for the following reasons:
> 
> * With an annotation, the generated JavaDoc gives you a list with all
> incubating members out of the box, see e.g. the Guava docs for an example
> [1].

How out iic the box is that? Looking at our javadocs the class use tab is not active 
in any of our projects. Is that just because we are not using the right options for the
javadoc plugin or would we need a custom doclet (and styles)?

> * For an annotation we can provide proper documentation in form of JavaDoc,
> i.e. the user of the API can inspect the docs of @Incubating from within
> the IDE and learn about the rules behind it. For a tag, a user would only
> see the specific comment of a given instance.

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.

> * An annotation is more tool friendly, e.g. a user could easily find all
> references to @Incubating in her IDE

Again, provided the sources are attached. Unless of course we have a runtime retention.
This is by the way what Gradle uses for its @Incubating annotation. I think if we go down the
path of using annotations runtime retention might be the better option. Only this would allow
users to somehow build some tooling around it. The question is whether we want this annotation
to have a runtime retention. Somehow it has a strange aftertaste, at least for me.

> or even write an annotation processor
> or a custom CheckStyle rule issuing a build warning when using an
> incubating member

This would assume the user actually builds our sources. That's not the case. He uses them as libraries.

> Such an annotation would have a retention level of SOURCE similar to other
> documenting annotations such as @Generated.

See above. 

--Hardy