incubator-crunch-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Matthias Friedrich <m...@mafr.de>
Subject Re: Javadoc improvements
Date Tue, 09 Oct 2012 17:36:30 GMT
On Tuesday, 2012-10-09, Gabriel Reid wrote:
> On Mon, Oct 8, 2012 at 8:28 PM, Matthias Friedrich <matt@mafr.de> wrote:
[...] 
>> 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.

Since we have the static factories I think we don't need to show the
implementation packages. Is there anything in there users would want
to reference directly? I didn't find anything, but I'm not that
familiar with the code.

Hmm, regarding the file naming, I'm not sure which pattern we should
follow in general: a) have implementation packages that are excluded
from the docs and provide access via static factories from a base
package, or b) hide the base package, put factories next to the
implementation and make the implementation package private.

A lot of Crunch leans towards a) and it would be a major pain to
refactor it. On the other hand that's where our dependency cycles come
from, at least when the implementation packages depend on base :)
 
Regards,
  Matthias

Mime
View raw message