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. 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
