Javadoc for expressions

[katcharov]

Partial work for JAVA-4799

Covers boolean, date, number, integer, and expression, but not others, since PRs are still in progress.

There are naming changes, to parameters especially.

[stIncMale]

So far I reviewed only Expression.

[jyemin]

I've never, ever seen this done. Have you?

[katcharov]

I've seen abuses, though not the deprecation of equals in particular. I don't plan to argue for it or keep it, but I was worried that users will mistake it for eq, and was hoping for some creative way to address this.

[katcharov]

(I removed this)

[jyemin]

What do you plan to write here?

[katcharov]

I think:

A value that may be stored in or otherwise operated upon by MongoDB.

Followed by some less-dense variation on:

This API is a language binding: it is a way to use a remote system as if
it were a native Java API. It is a way to represent values and computations
in some "execution context". This API is also a Domain Specific Language: it
is the Java-native variant of MQL, which is used to query MongoDB or (more
broadly) to work with data on MongoDB.

It would be followed by a few paragraphs covering important points and gotchas.

[katcharov]

I added a long description (similar to Stream). Unsure which parts of it, if any, might be moved to the package docs (none are obviously unrelated to the type hierarchy of which this is the root).

[jyemin]

I know we've been over this, but I'm still having difficulty squaring this sentence with the service that this API actually provides in the context of a MongoDB application. To my ears, this sentence implies that there should be a method like boolean booleanValue() (just like java.lang.Boolean has) on this type, which of course makes no sense. If you had to write another paragraph expanding on what this means, what would it say?

[stIncMale]

Slack discussion: https://mongodb.slack.com/archives/GCKKT44RM/p1671122088820819.

[katcharov]

Rebased. Conflicts on switch/pass (none on MqlEx, which should confirm that the correct signature was used).

[stIncMale]

We need to make sure that the following unchecked methods are documented as such (I am using the annotation from #1068 to express what the user asserts when using any of these methods):

method	annotation
Branches.isArray	@MqlUnchecked(TYPE_ARGUMENT)
Branches.isMap	@MqlUnchecked(TYPE_ARGUMENT)
BranchesIntermediary.isArray	@MqlUnchecked(TYPE_ARGUMENT)
BranchesIntermediary.isMap	@MqlUnchecked(TYPE_ARGUMENT)
Expressions.currentAsMap	@MqlUnchecked(TYPE_ARGUMENT)
Expressions.ofMap(Bson)	@MqlUnchecked(TYPE_ARGUMENT)
Expression.isArrayOr	@MqlUnchecked(TYPE_ARGUMENT)
Expression.isMapOr	@MqlUnchecked(TYPE_ARGUMENT)
ArrayExpression.elementAt	@MqlUnchecked(PRESENT)
ArrayExpression.first	@MqlUnchecked(PRESENT)
ArrayExpression.last	@MqlUnchecked(PRESENT)
MapExpression.get(key)	@MqlUnchecked(PRESENT)
DocumentExpression.getField	@MqlUnchecked(PRESENT)
DocumentExpression.getBoolean(fieldName)	@MqlUnchecked({PRESENT, TYPE})
DocumentExpression.getNumber(fieldName)	@MqlUnchecked({PRESENT, TYPE})
DocumentExpression.getInteger(fieldName)	@MqlUnchecked({PRESENT, TYPE})
DocumentExpression.getString(fieldName)	@MqlUnchecked({PRESENT, TYPE})
DocumentExpression.getDate(fieldName)	@MqlUnchecked({PRESENT, TYPE})
DocumentExpression.getDocument(fieldName)	@MqlUnchecked({PRESENT, TYPE})
DocumentExpression.getMap(fieldName)	@MqlUnchecked({PRESENT, TYPE})
DocumentExpression.getArray(fieldName)	@MqlUnchecked({PRESENT, TYPE})

[katcharov]

I will apply this in the final doc PR which covers docs etc. (along with, for example, server version annotations).

[stIncMale]

Right, the annotation may be added later. This comment is about documenting all unchecked methods with text (unless you decide not to do so and use only the annotation instead, which is what I would have preferred). The reason I used the annotation in the table is to conveniently express what a user must assert.

[katcharov]

Please leave unresolved, for easier reference.

[stIncMale]

Note how this annotation is documented as not being a part of the public API despite residing in a non-internal package and being public. This is because we want to generate the API docs for this annotation, but we don't want users to use it either to annotate their code, or to analyze the code at compile time.