[hibernate-dev] Marking API members as incubating

[Emmanuel Bernard]

I remember a few discussion where something like that has been
contemplated. One thing that made us not do it AFAIR is that we would
need some kind of shared project to host this across ORM, OGM, SEARCH
etc. In the past we have deemed it not worth it.

Emmanuel

On Wed 2013-07-10 17:48, Gunnar Morling wrote:
> Hi,
> 
> Hardy and I have been musing about how to mark new API members (methods,
> classes etc.) which are still incubating or experimental.
> 
> Of course we have Alpha, Beta releases etc. but there can be cases where it
> makes sense to ship new functionality with a final release and still leave
> the door open for refinements in the next release based on user feedback.
> 
> 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.
> 
> 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].
> 
> * 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.
> 
> * An annotation is more tool friendly, e.g. a user could easily find all
> references to @Incubating in her IDE or even write an annotation processor
> or a custom CheckStyle rule issuing a build warning when using an
> incubating member
> 
> Such an annotation would have a retention level of SOURCE similar to other
> documenting annotations such as @Generated.
> 
> Any thoughts?
> 
> --Gunnar
> 
> [1]
> http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/annotations/class-use/Beta.html
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev