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@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
