On Mon, Oct 8, 2012 at 8:28 PM, Matthias Friedrich <[email protected]> wrote: > one thing I'd like to get into our next release is a first step > towards better API documentation. For this it would be helpful to > agree on a reduced set of packages intended for client use (the > "published" API).
+1, this is definitely a place where we can get a big gain in usability > > I used the javadoc tool's grouping and exclusion mechanism to only > display packages that I think should be part of the published API. > See [1] on how this could look like, compared to our current > documentation at [2]. Is this list correct? Did I miss something? In addition to the lib.join package that Josh mentioned, we might want to include the format-specific packages (i.e. seq, avro, text) under o.a.c.io. I'm not totally sure on this, as they are indirectly accessible via o.a.c.At and o.a.c.To, but with the file naming stuff I was looking at adding as part of CRUNCH-91, the file naming API was is available on the format-specific implementation classes. On the other hand, it could just be added to the At and To classes, and then this becomes a non-issue. > > With just some exclusions I got from 243 classes/interfaces down to > 158. We could reduce this even further by making implementation > classes package private where possible. I'll run an analysis as soon > as we have agreed on the set of published packages. > > I'm not sure about the "Other Packages" section. o.a.c.tool should > probably be removed, with its content thrown into the util package. > Part of the o.a.c.types looks like it would be better off in the > base package (PType, PTypeFamily) while the rest looks like helper > functionality for o.a.c.types.* that shouldn't be published. What > do you think? > > Regards, > Matthias > > [1] http://tmp.mafr.de/crunch/apidocs/0.4.0-incubating-SNAPSHOT/ > [2] http://incubator.apache.org/crunch/apidocs/0.3.0/
