batch of javadoc revisions for clarity and completeness - #671

The old "For a comprehensive introduction..." opening set the stage here a bit more for readers."

We could keep that general approach with something like:

"For some general information common to all four nulless annotations, see the package documentation. For a comprehensive introduction...."

(and similarly in the other files once we have something that we're happy with)

Okay this here in NonNull.java is my current proposal to duplicate to the other places.

"Where do I go for the unimportant general information?" :)

So I might cut that one word, but I don't mind it even as much as the joke suggests.

Eh, maybe it's not even that important? Can go either way. Will leave this open just a bit before I start cloning.

(I'm still overall more a fan of opening with "For some [important] general information..." than with "The package documentation," and I might like "See the package documentation..." somewhere in between how much I like those two, but I'm also still willing to let this go.)

I think you asked somewhere about where/whether to bother with {@link Nullable @Nullable} and likewise for @NonNull. I guess I'm in favor of always bothering?

Trying what I hope is a consistent policy, which is that if it seems like we're talking about what you see or write at the use-site then we need the @. I think that ended up applying in most cases.

By the way though, I mean, these annotations do get copied to a generated accessor method, so I guess that could have an effect?

• I think these were the only ones that jumped out to me as possibly "missing" the @. Above, we say "where @nullable and @nonnull are not applicable," and here we say "Nullable and NonNull are still meaningful," so, while I'm sure we can argue that there's a difference there, it seems unlikely that the average reader would expect a difference.
• Yes, they would end up being copied to the generated accessor method, so they would have an effect downstream. We were aware of that when we made our decision, but I think we might have felt more "We have bigger fish to fry" than "We feel that this is overwhelmingly the correct decision." I think that our goal was more to discourage people from writing it than to pretend that it wouldn't have an effect downstream.

"Where do I go for the unimportant general information?" :)

So I might cut that one word, but I don't mind it even as much as the joke suggests.

We have definitely used "context" in discussions of this before. My thoughts are:

• I am trying to remember whether we discussed it and decided to try to move toward / away from it. But I don't remember. I could also be thinking of some different word, like "scope." Oh, yes, here we go.
• My brain expects "a null-marked context." (Here's a post in which you used it both ways :)) Gemini cites JLS precedent at me:
  • "in a static context"
  • "in an assignment context"
  • "in a boolean/numeric context"
    • (I see only "in a numeric arithmetic context" in a quick search.)

JLS uses the word in two ways, as shown by your first example versus the others. The others are, like a "countable" noun, a single context is a place where some single thing gets plugged in. Chief example of course being "type context".

"In a static context" is different and if I were editing the JLS I might consider phrasing it "in static context" instead of implying it is a countable thing like the other cases. And this is the sense in which I'm trying to use the word here now. Purely: "hey what kind of context are we currently in here, A or B?" Our case is the cleaner one since I think "static context" is relative to which containing class you're talking about.

Good 'nuff?

For "type context," I'm seeing "a type context," "type contexts," and "any type context," right?

It's reasonable to argue that the JLS should drop the "the" as a more general rule, and I don't need to push on that if you just want to buck the trend, but to check: Are we in agreement that you are in fact bucking the JLS trend, or is there more that hasn't yet registered with me?

Not sure what your first question means, but those are all valid phrases treating type contexts as the "countable kind of context" if you want to think of it that way.

Then there are the other kind, of which we've noted two examples, "static context", and "null-marked context". The way I see it, as far as a user knows maybe JSpecify does have weird rules to learn of the form "sure, that's true for that null-marked context, but not for the other null-marked context that is three null-marked contexts down from where you are." It's relevant that we don't have any rules like that, so I thinks, I'll drop the "a".

That makes sense. I think I prefer "code" to "context": Even with you explanation, "null-marked context" continues to jump out to me, and I'd expect it to jump out a bit to a decent number of other users. Plus, it's longer, and it's one of those words that is used so widely for Java class names (and often in ways that would have me clutching my pearls) that it doesn't really add anything from my perspective. I am not particularly invested in the phrasing here, either, but I assume you have a sales pitch for "context," and I'm up for trying to evaluate it if that sounds like a good time to you.

This is oh very subjective, but for whatever reason, "null-marked code" gives me slightly more of a "but what do they mean by 'code'? What is the definition of 'code' here?" reaction. Whereas somehow when I hit "context" I don't feel like it might be implying something specific I have to go learn about. I dunno.

• I think these were the only ones that jumped out to me as possibly "missing" the @. Above, we say "where @nullable and @nonnull are not applicable," and here we say "Nullable and NonNull are still meaningful," so, while I'm sure we can argue that there's a difference there, it seems unlikely that the average reader would expect a difference.
• Yes, they would end up being copied to the generated accessor method, so they would have an effect downstream. We were aware of that when we made our decision, but I think we might have felt more "We have bigger fish to fry" than "We feel that this is overwhelmingly the correct decision." I think that our goal was more to discourage people from writing it than to pretend that it wouldn't have an effect downstream.

(I'm still overall more a fan of opening with "For some [important] general information..." than with "The package documentation," and I might like "See the package documentation..." somewhere in between how much I like those two, but I'm also still willing to let this go.)

That makes sense. I think I prefer "code" to "context": Even with you explanation, "null-marked context" continues to jump out to me, and I'd expect it to jump out a bit to a decent number of other users. Plus, it's longer, and it's one of those words that is used so widely for Java class names (and often in ways that would have me clutching my pearls) that it doesn't really add anything from my perspective. I am not particularly invested in the phrasing here, either, but I assume you have a sales pitch for "context," and I'm up for trying to evaluate it if that sounds like a good time to you.