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

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