Re: [hibernate-dev] Marking API members as incubating
2013/7/11 Hardy Ferentschik <hardy(a)hibernate.org>
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)?
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(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hibernate-dev