`copyOf` in immutable collections does not document throwing NPE when argument is null

[Xaerxess]

To my surprise none of copyOf methods in immutable collections (ex. ImmutableList#copyOf(Collection)) document throwing NPE when copied collection / iterable / array is null itself. I believe it's not side-effect behavior but rather your intended action.

Currently you only have:

Throws: NullPointerException - if any of elements is null

but IMO it should also state something more explicit regarding elements variable being null.

[cpovirk]

We should see what we do elsewhere.

We intend for rejecting null parameters to be the default. The official documentation of that is @ParametersAreNonNullByDefault on each package.

That said, I thought that we tried to explicitly say "if foo is null" in cases where we already have to say "if any element in foo is null." If someone can dig up examples, that might help us figure out whether to zig or zag. Or maybe we already made an official decision one way or the other here that I don't remember. Anyone?

[cpovirk]

Now that we annotate extensively for nullness, there is a general question of how much to document the behavior users would get when they pass null: Part of the benefit of annotating is that we're effectively declaring null to be... I wouldn't say exactly "undefined behavior" but at least somewhat "out of scope." Like, you shouldn't put it in. The specific way that we'd react if you try to put it in should be the least of your concerns. That said, we do play up the advantages of eager null-hostility in the immutable collections in particular, so we might feel motivated to continue mentioning it in the Javadoc for that reason.

(I think we may have a separate bug about this somewhere internally....)