Re: [hibernate-dev] Marking API members as incubating

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(a)hibernate.org&gt; 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/... >>> _______________________________________________ >>> hibernate-dev mailing list >>> hibernate-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/hibernate-dev >> _______________________________________________ >> hibernate-dev mailing list >> hibernate-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hibernate-dev > _______________________________________________ > hibernate-dev mailing list > hibernate-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev _______________________________________________ hibernate-dev mailing list hibernate-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev