Annotate CodeSource.

[cpovirk]

No description provided.

[wmdietl]

One point of discussion, all other additions are consistent with javadoc.

[wmdietl]

The first condition says <li> <i>codesource</i> must not be null. also the @param doesn't mention null.
The implementation clearly returns false if the parameter is null, which is consistent with the If any fail, it returns {@code false}. in the javadoc.

This looks like another instance of our discussions about how to annotate methods where null is forbidden, but no NPE is thrown.
I'm fine with making it Nullable, if that is more convenient for the uses of the method that you see.

[cpovirk]

Thanks.

I found this Javadoc a bit vexing. Normally, I read "must" as expressing a precondition in the sense of "This method will throw (or at 'best' have undefined behavior) if the precondition is not met." But the way the Javadoc here is phrased, it seems to be consistently using the word "must" to express "The method returns true if all these 'musts' are met and false otherwise." Hence we have "This object's protocol... must be equal to codesource's protocol" in parallel to "codesource's location must not be null." But then, just when it looks like everything is phrased consistently, we have a bullet that suggests that the whole list should have been expressed in pseudocode: "If this object's location equals codesource's location, then return true."

Given that, I do feel OK with this annotation. I should record, though, that don't think it was prompted by a specific need in our code: I think that we needed CodeSource(URL url, Certificate[] certs) to have a @Nullable on that second parameter, and I decided to go for the whole file. (It's possible that I was also confused and thought that we needed a bit more because I was mixing up a null passed to CodeSource and a call passed to ProtectionDomain in the same statement :)) Let me punt things back to you in case my confession leaves you reluctant here.

[wmdietl]

Thanks for the detailed analysis. I'm fine with keeping this annotation. If anyone has an issue, they'll see this discussion and can argue against it.