doc: Apply suggestions from code review

Co-authored-by: Jurriaan Persyn <oemebamo@gmail.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 3 people

docs/src/modules/ROOT/pages/quickstart/overview.adoc

@@ -47,7 +47,7 @@ Deploy a fully isolated optimization service. This opinionated approach reduces
 
 | *Best for*
 | Embedding the solver into an existing application
-| Running optimization as a standalone, isolated service
+| Running optimization as a standalone, isolated service that is easier to integrate, orchestrate & scale
 
 | *Ease of use*
 | Requires manual wiring: you manage configuration, lifecycle, and integration

docs/src/modules/ROOT/pages/quickstart/shared/_whatyoubuild.adoc

@@ -2,7 +2,7 @@
 
 You will build an optimization solution that runs locally on your machine, and optimizes a school timetable for students and teachers.
 
-Your application will assign `Lessons` to `Timeslots` and `Rooms` automatically
+Your application will assign `Lesson` instances to `Timeslot` and `Room` instances automatically
 by using AI to adhere to hard and soft scheduling _constraints_, for example:
 
 * A room can have at most one lesson at the same time.

docs/src/modules/ROOT/pages/quickstart/shared/school-timetabling/_school-timetabling-constraints.adoc

@@ -19,7 +19,7 @@ Soft constraints are weighted too, against other soft constraints.
 *Hard constraints always outweigh soft constraints*, regardless of their respective weights.
 
 To calculate the score, implement a `TimetableConstraintProvider` class.
-It uses Timefold Solver's xref:https://docs.timefold.ai/timefold-solver/latest/constraints-and-score/score-calculation[Constraint Streams API]
+It uses Timefold Solver's xref:constraints-and-score/score-calculation.adoc[Constraint Streams API]
 which is inspired by Java Streams and SQL:
 
 [tabs]

docs/src/modules/ROOT/pages/service/constraint-weights.adoc

@@ -97,14 +97,14 @@ Next, in the xref:./rest-api.adoc#modelConverter[model converter], make sure to
 ----
 TimetableConfigOverrides modelConfigOverrides = modelConfig.overrides();
 
-ConstraintWeightOverrides<HardMediumSoftLongScore> constraintWeightOverrides = ConstraintWeightOverrides.none();
-constraintWeightOverrides = ConstraintWeightOverrides.of(
-                    Map.ofEntries(
-                        Map.entry(TEACHER_CONFLICT,
-                                HardMediumSoftLongScore.ofHard(modelConfigOverrides.getTeacherConflictWeight())),
-                        Map.entry(ROOM_COMFLICT,
-                                HardMediumSoftLongScore
-                                        .ofSoft(modelConfigOverrides.getRoomConflictWeight()));
+ConstraintWeightOverrides<HardMediumSoftLongScore> constraintWeightOverrides = ConstraintWeightOverrides.of(
+        Map.ofEntries(
+                Map.entry(TimetableConstraintProvider.TEACHER_CONFLICT,
+                        HardMediumSoftLongScore.ofHard(modelConfigOverrides.getTeacherConflictWeight())),
+                Map.entry(TimetableConstraintProvider.ROOM_CONFLICT,
+                        HardMediumSoftLongScore.ofSoft(modelConfigOverrides.getRoomConflictWeight()))
+        )
+);
 
 solverModel.setConstraintWeightOverrides(constraintWeightOverrides);
 ----

docs/src/modules/ROOT/pages/service/rest-api.adoc

@@ -69,7 +69,7 @@ If your model provides xref:./demo-data.adoc[demo data], the following endpoints
 == Request and response structure
 
 The generated endpoints do not accept/return the pure `ModelInput`/`ModelOutput` objects as JSON.
-Instead, a fixed envelop is used for both the requests and responses of solver actions.
+Instead, a fixed envelope is used for both the requests and responses of solver actions.
 
 === Structured solving request
 
@@ -158,7 +158,7 @@ Additionally, more fields might be added for specific model implementations:
       "warnings": []
     }
   },
-  "modelOutput": <ModelOutput class as JSON>,
+  "modelOutput": "<ModelOutput class as JSON>",
   "inputMetrics": {
     "lessons": 200,
     "timeslots": 50
@@ -202,20 +202,21 @@ To convert between `ModelInput` / `ModelOutput` and the `SolverModel`, a `ModelC
 [source,java,options="nowrap"]
 ----
 @ApplicationScoped
-public class TimetableConvertor implements ModelConvertor<HardSoftLongScore, TimetableDto, Timetable, EmptyModelConfigOverrides, EmptyModelInputMetrics, EmptyModelOutputMetrics, Timetable> {
+public class TimetableConvertor implements ModelConvertor<HardSoftLongScore, TimetableDto, EmptyModelConfigOverrides, Timetable, TimetableDto> {
 
     @Override
-    public Timetable toSolverModel(TimetableDto modelInput, TimetableDto previousModelOutput, ModelConfig<EmptyModelConfigOverrides> modelConfig) {
+    public Timetable toSolverModel(TimetableDto modelInput, ModelConfig<EmptyModelConfigOverrides> modelConfig,
+            Optional<TimetableDto> lastModelOutput) {
         return // Mapping logic
     }
 
     @Override
-    public Timetable toSolverModel(TimetableDto modelInput, ModelConfig<EmptyModelConfigOverrides> modelConfig) {
+    public TimetableDto toModelOutput(Timetable solverModel) {
         return // Mapping logic
     }
 
     @Override
-    public TimetableDto toModelOutput(Timetable solverModel) {
+    public TimetableDto applyOutputToInput(TimetableDto modelInput, TimetableDto modelOutput) {
         return // Mapping logic
     }
 }
@@ -309,11 +310,11 @@ The `metadata` object is a part of the model response json and contains the vali
 
 Additionally, a richer validation result can be obtained by a dedicated REST endpoint:
 
-`GET /v1/timetables/+{id}+/validation-result`
+`GET /v1/timetables/\{id\}/validation-result`
 
 Assuming the xref:timetableValidatorExample[example TimetableValidator], the endpoint provides the following response:
 
-.Validation result available via `GET /v1/timetables/+{id}+/validation-result`.
+.Validation result available via `GET /v1/timetables/\{id\}/validation-result`.
 [source,json, highlight=13..17]
 ----
 {

docs/src/modules/ROOT/pages/using-timefold-solver/running-the-solver.adoc

@@ -5,7 +5,7 @@
 :sectnums:
 :icons: font
 :relevance: core-only
-:notes: Too much things service module does automatically or with 1 single configuration.
+:notes: Too many things the service module does automatically, or with a single configuration.
 
 [#theSolverInterface]
 == The `Solver` interface