On 12 January 2014 10:18, Stefan Bodewig <bode...@apache.org> wrote: > Compress holds a package that is public as an implementation detail but > whose API isn't meant for public consumption. The javadocs of said > package state this in bold letters.[1] > > Current trunk will even go further and hide the package from javadoc, > but the only class inside is still refered to by two stream classes that > inherit from it (ZCompressorInputStream and UnshrinkingInputStream). > > I'm a bit torn on this and since I'll re-roll a new RC anyway I'd like > to see what others think about hiding internal packages.
I think it's better to keep the Javadoc, and be explicit about not using it, rather than hoping people won't use classes that don't happen to have Javadoc. It's not possible for a user to tell if the Javadoc is deliberately or accidentally missing [1]. In fact I would go a bit further and change the class Javadoc: Base-class for traditional Unix ".Z" compression and the Unshrinking method of ZIP archive. to add something like "Internal use only. May change or disappear without warning.". [1] Remember the manual pages which stated "This page is intentionally left blank"? Similar reasoning here. > Stefan > > [1] > http://people.apache.org/~bodewig/cc-1.7/apidocs/org/apache/commons/compress/compressors/z/_internal_/package-summary.html > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
