On Tue, Oct 9, 2012 at 7:36 PM, Matthias Friedrich <[email protected]> wrote: > On Tuesday, 2012-10-09, Gabriel Reid wrote: >> On Mon, Oct 8, 2012 at 8:28 PM, Matthias Friedrich <[email protected]> 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.
