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 19:05:59 GMT
On Tue, Oct 9, 2012 at 7:36 PM, Matthias Friedrich <matt@mafr.de> wrote:
> 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.

Ok, good point -- this just means that we need to expand the static
factories with some extra methods, but I'm fine with that.

>
> 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 :)

Yes, I definitely think we should stick with the static factories, but
there is quite a bit of stuff that we can untangle there as well.

Mime
View raw message