[hibernate-dev] Marking API members as incubating

[Steve Ebersole]

http://www.gradle.org/docs/current/userguide/feature_lifecycle.html

I sometimes think about a similar approach (in terms of using 
annotations) to marking the API/SPI/INTERNAL split.

On 07/10/2013 11:23 AM, Sanne Grinovero wrote:
> 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
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev