[hibernate-dev] Marking API members as incubating

[Steve Ebersole]

The Gradle team do this exact thing as well.  They have been doing that 
for over a year.  You might want to ask them about their experiences.

On 07/10/2013 10:48 AM, 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