feat: add nullness annotations on public API (WIP)

[greyhairredbear]

Opening this draft PR to see CI results for javadoc & collect early feedback

Open items (remaining open items are to be delivered with #1160)

• domain
• impl related to domain package
• function
• impl related to function package
• score
• score.analysis
• score.buildin
• score.calculator
• score.constraint
• score.director
• score.stream
• score.stream.bi
• score.stream.common
• missing annotations in score.stream.common.ConstraintCollectors
• score.stream.penta
• score.stream.quad
• score.stream.tri
• score.stream.uni
• impl related to score package
• solver
• (re)check if all impl related to solver package has been annotated
• config
• timefold-solver-benchmark
• timefold-solver-test
• check format :)
• collect open todos and resolve together with maintainer

Skipped (for now):

• annotation attributes (e.g. PiggybackShadowVariable.shadowVariableName) - not sure if this would be valuable. IDE complains "Attribute value must be constant" when trying to assign null here. If there is value in this because the solver internally uses these attributes, I'd be ok with adding these too.
• deprecated classes and methods

[triceo]

Thanks for the PR, @greyhairredbear!
I'll review once the PR is undrafted.

[triceo]

FYI @greyhairredbear:

• The code coverage metric from Sonar is likely not relevant in this case. You're mostly be touching the API code here, so don't let it discourage you.
• Please also think of the config package. Even though it's technically not api, people are likely to use it and we treat it as public API.
• There are APIs in the timefold-solver-benchmark and timefold-solver-test module too.

[sonarqubecloud]

Quality Gate failed

Failed conditions
66.7% Coverage on New Code (required ≥ 70%)

See analysis details on SonarCloud

[greyhairredbear]

@greyhairredbear My other PR is ready to go and I need to merge it before the end of the week. Is there anything else you intend to do here before marking this as "Ready for review"?

(The actual review is already done.)

Sorry, I thought this was waiting for #1149 to be completed - but I just saw some tests there are still failing because Java 21 is not supported.

I guess it's ok to merge this, so I'll undraft it. Please don't hesitate to contact me if there are any issues related to this, I'd be glad to help and don't want to block anybody.

I'll open a new PR with the remaining tasks and reference it from here once I start working on the remaining changes.

[triceo]

Thank you, @greyhairredbear! I will merge this later today.
As agreed, I'm looking forward to the rest of this great work on/before Nov 3rd!

[sonarqubecloud]

Quality Gate failed

Failed conditions
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarCloud

Catch issues before they fail your Quality Gate with our IDE extension SonarLint