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

- generate two JavaDoc bundles: one which only contains the public API/SPIs and one with everything Tristan _______________________________________________ infinispan-dev mailing list infinispan-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev

On 26/02/2014 15:02, Mircea Markus wrote: > On Feb 26, 2014, at 1:05 PM, Tristan Tarrant <ttarrant(a)redhat.com&gt; 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.