Re: [hibernate-dev] Marking API members as incubating
On 10 Jan 2013, at 5:48 PM, Gunnar Morling <gunnar(a)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)?
* 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.
* 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.
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