2013/7/11 Hardy Ferentschik <ha...@hibernate.org> > > On 10 Jan 2013, at 5:48 PM, Gunnar Morling <gun...@hibernate.org> wrote: > > > 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. > > I think that is the easiest. IMO that is sufficient. > > > 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]. > > How out iic the box is that? Looking at our javadocs the class use tab is > not active > in any of our projects. Is that just because we are not using the right > options for the > javadoc plugin or would we need a custom doclet (and styles)? >
That's a good question. There is a "Uses" tab at least in the HV docs, but it seems only sparsely populated. I'd need to look into this in more detail. > > > * 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. > > Here is the thing, we need to also need to start talking retention setting > of the annotation. > I think you were suggesting source retention. This means that the > annotation is only in the > source. That means the IDE needs to be linked to the source. I would > assume that often > developers will setup their IDEs to download sources automatically, but it > is not a given. > Yes, you're right. See my response to Sanne's previous message: > Btw. I got the retention wrong in my first message, it should be CLASS so a user can see whether its present on any API members. For the reasons you describe, SOURCE indeed is wrong, but I think CLASS would suffice (that's also what Guava's @Beta uses) which puts it into the class files of types using it. Or is there a need to access the annotation reflectively at runtime? > > * An annotation is more tool friendly, e.g. a user could easily find all > > references to @Incubating in her IDE > > Again, provided the sources are attached. Unless of course we have a > runtime retention. > This is by the way what Gradle uses for its @Incubating annotation. I > think if we go down the > path of using annotations runtime retention might be the better option. > Only this would allow > users to somehow build some tooling around it. The question is whether we > want this annotation > to have a runtime retention. Somehow it has a strange aftertaste, at least > for me. > Would the aftertaste be gone with using CLASS retention? > > or even write an annotation processor > > or a custom CheckStyle rule issuing a build warning when using an > > incubating member > > This would assume the user actually builds our sources. That's not the > case. He uses them as libraries. > > > Such an annotation would have a retention level of SOURCE similar to > other > > documenting annotations such as @Generated. > > See above. > > --Hardy > _______________________________________________ > 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
