[hibernate-dev] Marking API members as incubating

[Gunnar Morling]

2013/7/11 Hardy Ferentschik <hardy at hibernate.org>

>
> On 10 Jan 2013, at 5:48 PM, Gunnar Morling <gunnar at 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 at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>