[infinispan-dev] JavaDocs and API documentation

[Dan Berindei]

On Wed, Feb 26, 2014 at 4:24 PM, Tristan Tarrant <ttarrant at redhat.com>wrote:

> On 26/02/2014 15:02, Mircea Markus wrote:
> > On Feb 26, 2014, at 1:05 PM, Tristan Tarrant <ttarrant at redhat.com>
> wrote:
> >
> >> Dear all,
> >>
> >> our JavaDocs currently encompass all of our classes, interfaces, etc
> >> with no clear distinction between public and private API/SPI. I would
> >> like to clearly mark which of our classes/interfaces are public API.
> >> Should we:
> >>
> >> - add some decoration / visual cue to such elements to distinguish them
> >> from the internal stuff
> > I think Sanne mentioned and i think it was Hibernate that has impl
> sub-packages for all the non-public API.
> > Sounds sensible to me, as people will see the impl in the class name
> when importing it, and that should raise question marks. shall we adopt
> that?
> That would help, but we would still end up with a lot of noise in the
> javadocs, for example the list of classes on the left has no separation
> by package.
>
>
If we move all internal classes to .impl sub-packages, it will be quite
easy to exclude the .impl packages from javadocs with a bit of
maven-javadoc-plugin configuration. I don't think we need to generate
javadocs for the internal classes at all, as the sources are easily
accessible from any IDE.

Cheers
Dan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/infinispan-dev/attachments/20140226/d831716b/attachment-0001.html