crunch-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gabriel Reid <gabriel.r...@gmail.com>
Subject Re: Javadoc improvements
Date Tue, 09 Oct 2012 11:15:31 GMT
On Mon, Oct 8, 2012 at 8:28 PM, Matthias Friedrich <matt@mafr.de> 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/

Mime
View raw message