Annotate Gatherer APIs.

[cpovirk]

No description provided.

[wmdietl]

These look like they were missed, but I don't know this API:

default <RR> Gatherer<T, ?, RR> andThen(Gatherer<? super R, ?, ? extends RR> that) on line 274 in Gatherer: shouldn't RR allow null?
static <A> Supplier<A> defaultInitializer() on line 289 and static <A> BinaryOperator<A> defaultCombiner() on line 304 in Gatherer: should A allow null?
static <A, R> BiConsumer<A, Downstream<? super R>> defaultFinisher() { on line 321 in Gatherer: A and R should be nullable?

[cpovirk]

Thanks, I had totally missed those.

andThen looks straightforward, assuming that I haven't been missing anything big throughout this PR.

The others are more interesting. The implementations of default* methods all look capable of handling null—or, in the case of the BinaryOperator for combiner(), as incapable of handling null as of any other value (and I think this point is that the Gatherer infrastructure treats combiner() as a sentinel that says not to invoke the method). There are two things that make that interesting:

• First, the initializer() returns null. I think that means that we actually want to return a Supplier<@Nullable A>.
• Second, the Gatherer API doesn't do PECS. That means that we probably shouldn't force other methods (like defaultCombiner()) to return a more general type, which is to say BinaryOperator<@Nullable A> (since we can't change it to the fully general type BinaryOperator<@Nullable Object>, since that would require a change to the base type). So I think it makes sense to let callers pick their nullness, just as they can pick the base type.

I have never actually used these APIs, so I could well still be missing things. I would be OK with waiting to merge this until I can justify taking the time to investigate more deeply, or we could go for it and figure that we'll get feedback if users encounter actual problems.

[wmdietl]

Sorry, I had missed that this was updated. I merged in main and things look good to me.