docs: document updating multiple fields with custom shadow variables

[TomCools]

Solves #2472

document how to update multiple fields with a custom shadow variable.

[Copilot]

Pull request overview

This PR updates the domain-modeling documentation to explain how to update multiple related pieces of declarative shadow state by grouping them into a single wrapper (e.g., a Java record) and exposing the individual values via accessors, addressing #2472.

Changes:

• Added a new documentation section describing the “wrapper object” approach for computing multiple related shadow values together.
• Included a Java example using a JobState record as the single shadow variable value.
• Adjusted several nearby section titles to sentence case (“… shadow variables”).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

[triceo]

@Christopher-Chianelli Please take a look.

[TomCools]

@Christopher-Chianelli , not too sure if the supplier method MUST be public or not. Good to clarify.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

docs/src/modules/ROOT/pages/domain-modeling/modeling-planning-problems.adoc:2034

• jobStateSupplier() can throw a NullPointerException if previous is non-null but previous.jobState has not been initialized yet, because it dereferences previous.jobState.endDate() without a null guard.

This issue also appears on line 2043 of the same file.

        LocalDate readyDate = previous == null ? null : previous.jobState.endDate();

docs/src/modules/ROOT/pages/domain-modeling/modeling-planning-problems.adoc:2037

• jobStateSupplier() can throw a NullPointerException when earliestStartDate is null and readyDate is non-null due to calling readyDate.isBefore(earliestStartDate).

        LocalDate startDate = readyDate == null || readyDate.isBefore(earliestStartDate) ? earliestStartDate : readyDate;

docs/src/modules/ROOT/pages/domain-modeling/modeling-planning-problems.adoc:2043

• jobStateSupplier() can throw a NullPointerException if previous is non-null but previous.jobState is null, because it calls previous.jobState.totalDurationInDays() without a null guard.

        int totalDurationInDays = (previous == null ? 0 : previous.jobState.totalDurationInDays()) + durationInDays;

[TomCools]

@triceo , you may have removed yourself from the reviewer list, but this isn't getting merged without you as gatekeeper (Waiting on required approvals from TimefoldAI/timefold-solver-gatekeepers)

[triceo]

@TomCools Good point that I probably shouldn't be removing myself if I know I'll eventually be needed there; I will certainly not remove myself on PRs where I want/need to be involved.

For others, you can @ the gatekeepers group and anyone can do it. Considering people's response times, it's most likely going to be me anyway. :-)