[hibernate-dev] Marking API members as incubating

[Sanne Grinovero]

To share the annotation?
We where contemplating a shared jar anyway to maintain the checkstyle
rules. I guess this could also contain some other shared stuff, like
the CSS extensions to the javadoc, etc..

On 10 July 2013 17:13, Emmanuel Bernard <emmanuel at hibernate.org> wrote:
> 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
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev