Thanks for the comments, Joe and Jay. Doing the public / private designation at package level is definitely easier than going method-by-method :)
If I get your comments right, the idea is to publish java docs for the public apis on our website (or archive.apache.org) and not publish java docs for the private apis. The pros to that approach is that it doesn't require going through every single public method in our code-base and marking it private or public. I'm definitely not looking forward to that patch. The cons is that open source developers don't necessarily assume that lack of java docs imply that a method is not public... they usually assume that the project was sloppy about its docs. I think the pros win here :) Regarding the location of the javadocs - the website, via SVN is traditional, and probably more google-able. Updating the SVN shouldn't be too-painful to do as part of the release process? Right now googling for "kafka javadoc" does not lead the to latest 0.8.2 docs. I'm getting github, stackoverflow and Neha's private apache page. Then there's the other attribute - which API is stable. Currently Kafka pretty much assumes an API is stable from the moment its committed to the trunk, I believe. It may make the development process slightly easier if we can mark new APIs as "evolving" until we are certain we are happy with them. It will allow us to iterate faster and let users try out newer APIs. Do you think adding this will be helpful? On Tue, Dec 16, 2014 at 11:24 AM, Jay Kreps <jay.kr...@gmail.com> wrote: > Hey Gwen, > > We discussed this a bit about this when starting on the new clients. > > We were super sloppy about this in initial Kafka development--single jar, > no real differentiation between public and private apis. > > The plan was something like the following: > 1. Start to consider this with the new clients. > 2. Do the public/private designation at the package level. The public > packages are o.a.k.common, o.a.k.errors, o.a.k.producer, o.a.k.consumer, > o.a.k.tools. This makes javadoc and things like that easier, and it makes > it easy to see at a glance all the public classes. It would be even better > to enforce this in the build if that is possible (i.e. no class from a > non-public package is leaked) but we haven't done this. This approach > obviously wasn't possible in Hadoop since they started without a clear > delineation as we did in the original scala code. > > Thoughts? > > -Jay > > > On Tue, Dec 16, 2014 at 10:04 AM, Gwen Shapira <gshap...@cloudera.com> > wrote: >> >> Hi, >> >> Kafka has public APIs in Java and Scala, intended for use by external >> developers. >> In addition, Kafka also exposes many public methods that are intended >> to use within Kafka but are not intended to be called by external >> developers. >> Also, some of the external APIs are less stable than others (the new >> producer for example). >> >> In Hadoop we have a similar situation, and to avoid misunderstandings >> or miscommunications on which APIs are external and which are stable, >> we use annotations to communicate this information. >> We find it very useful in preventing our customers from accidentally >> getting into trouble by using internal methods or unstable APIs. >> >> Here are the annotations Hadoop uses: >> >> https://hadoop.apache.org/docs/current/api/src-html/org/apache/hadoop/classification/InterfaceStability.html >> >> https://hadoop.apache.org/docs/current/api/src-html/org/apache/hadoop/classification/InterfaceAudience.html >> >> I'm wondering what others think about using something similar in Kafka. >> >> Gwen >>
