chore: add more code comments

core/src/ten_manager/src/solver/display.lp

@@ -1,17 +1,27 @@
 %=============================================================================-
 % Display Results
 %
-% This section determines what parts of the model are printed at the end
+% This section determines what parts of the model are printed at the end.
 %==============================================================================
 
 % Spec-related functions.
 % Used to build the result of the solve.
 #show selected_pkg_version/3.
 
+% Used to build the dependency chain.
 #show introducer/6.
 
 % error types
+#show error/2.
+#show error/3.
+#show error/4.
+#show error/5.
 #show error/6.
+#show error/7.
+#show error/8.
+#show error/9.
+#show error/10.
+#show error/11.
 #show error/12.
 
 % debug

core/src/ten_manager/src/solver/main.lp

@@ -1,22 +1,43 @@
 % The rule for predicate names: Predicate names ending with '_declared' are
-% definitely defined by the user (from Clingo's perspective).
+% defined by the user (from Clingo's perspective).
 
 %-----------------------------------------------------------------------------
 % Declaration
 %-----------------------------------------------------------------------------
 
 % do not warn if generated program contains none of these.
 % 'error' is intentionally left undefined within the logic program.
+% The purpose of the 'error' is to output a standardized error message in the
+% output model, allowing Clingo users to understand the issue with the model.
+% This way, the corresponding error message can be displayed in the terminal,
+% informing the end user about the problem with the model.
+#defined error/2.
+#defined error/3.
+#defined error/4.
+#defined error/5.
 #defined error/6.
+#defined error/7.
+#defined error/8.
+#defined error/9.
+#defined error/10.
+#defined error/11.
 #defined error/12.
 
 %-----------------------------------------------------------------------------
 % Version semantics
 %-----------------------------------------------------------------------------
 
 % If a package is selected (selected_pkg == true), then choose at least 1
-% versions (selected_pkg_version) from all available versions of that package
+% version (selected_pkg_version) from all available versions of that package
 % (version_declared).
+%
+% In the end, there might not be a perfect dependency tree, but rather
+% dependency conflicts. Dependency conflict means that two versions of a package
+% have been selected in different dependency paths. To display better error
+% messages in the terminal, we choose not to restrict each package to only one
+% version but instead allow selecting more than one version, with an additional
+% error statement to check for such errors. This way, when there’s no perfect
+% model, we can show a clearer error message for models with errors.
 1 <= { selected_pkg_version(PkgType, PkgName, PkgVersion) : version_declared(PkgType, PkgName, PkgVersion, PkgWeight) }
   :- selected_pkg(PkgType, PkgName).
 
@@ -76,15 +97,15 @@ introducer(PkgType, PkgName, PkgVersion, "root", "", "")
 :- not version_declared(PkgType, PkgName, PkgVersion, _),
    depends_on_declared(_, _, PkgType, PkgName, PkgVersion).
 
-% Select only 1 version for the dependency package.
+% Prevent selecting undeclared package versions.
+:- not version_declared(PkgType, PkgName, PkgVersion, _),
+   selected_pkg_version(PkgType, PkgName, PkgVersion).
+
+% Select at least 1 version for the dependency package.
 1 <= { depends_on(PkgType, PkgName, PkgVersion, DepType, DepName, DepVersion) : depends_on_declared(PkgType, PkgName, PkgVersion, DepType, DepName, DepVersion) }
   :- selected_pkg_version(PkgType, PkgName, PkgVersion),
      depends_on_declared(PkgType, PkgName, PkgVersion, DepType, DepName, _).
 
-% Prevent selecting undeclared package versions.
-:- selected_pkg_version(PkgType, PkgName, PkgVersion),
-   not version_declared(PkgType, PkgName, PkgVersion, _).
-
 % 'depends_on' imply new 'selected_pkg_version'.
 selected_pkg_version(DepType, DepName, DepVersion)
   :- depends_on(PkgType, PkgName, _, DepType, DepName, DepVersion).
@@ -128,8 +149,16 @@ needed(DepType, DepName)
 %-----------------------------------------------------------------------------
 
 % Some errors are handled as rules instead of constraints because it allows us
-% to explain why something failed. Here we optimize HEAVILY against the facts
-% generated by those rules.
+% to explain why something failed.
 
+#minimize{ ErrWeight@1000,Msg: error(ErrWeight, Msg) }.
+#minimize{ ErrWeight@1000,Msg,Arg1: error(ErrWeight, Msg, Arg1) }.
+#minimize{ ErrWeight@1000,Msg,Arg1,Arg2: error(ErrWeight, Msg, Arg1, Arg2) }.
+#minimize{ ErrWeight@1000,Msg,Arg1,Arg2,Arg3: error(ErrWeight, Msg, Arg1, Arg2, Arg3) }.
 #minimize{ ErrWeight@1000,Msg,Arg1,Arg2,Arg3,Arg4: error(ErrWeight, Msg, Arg1, Arg2, Arg3, Arg4) }.
+#minimize{ ErrWeight@1000,Msg,Arg1,Arg2,Arg3,Arg4,Arg5: error(ErrWeight, Msg, Arg1, Arg2, Arg3, Arg4, Arg5) }.
+#minimize{ ErrWeight@1000,Msg,Arg1,Arg2,Arg3,Arg4,Arg5,Arg6: error(ErrWeight, Msg, Arg1, Arg2, Arg3, Arg4, Arg5, Arg6) }.
+#minimize{ ErrWeight@1000,Msg,Arg1,Arg2,Arg3,Arg4,Arg5,Arg6,Arg7: error(ErrWeight, Msg, Arg1, Arg2, Arg3, Arg4, Arg5, Arg6, Arg7) }.
+#minimize{ ErrWeight@1000,Msg,Arg1,Arg2,Arg3,Arg4,Arg5,Arg6,Arg7,Arg8: error(ErrWeight, Msg, Arg1, Arg2, Arg3, Arg4, Arg5, Arg6, Arg7, Arg8) }.
+#minimize{ ErrWeight@1000,Msg,Arg1,Arg2,Arg3,Arg4,Arg5,Arg6,Arg7,Arg8,Arg9: error(ErrWeight, Msg, Arg1, Arg2, Arg3, Arg4, Arg5, Arg6, Arg7, Arg8, Arg9) }.
 #minimize{ ErrWeight@1000,Msg,Arg1,Arg2,Arg3,Arg4,Arg5,Arg6,Arg7,Arg8,Arg9,Arg10: error(ErrWeight, Msg, Arg1, Arg2, Arg3, Arg4, Arg5, Arg6, Arg7, Arg8, Arg9, Arg10) }.

core/src/ten_manager/src/solver/solve.rs

@@ -179,11 +179,13 @@ fn solve(
         conf.value_set(solve_models_key, "0")
             .expect("Failed to set solve.models to 0.");
 
+        // Configure to enumerate all optimal models.
         let solve_opt_mode_key =
             conf.map_at(root_key, "solve.opt_mode").unwrap();
         conf.value_set(solve_opt_mode_key, "optN")
             .expect("Failed to set solve.opt_mode to optN.");
 
+        // Enable full statistics.
         let stats_key = conf.map_at(root_key, "stats").unwrap();
         conf.value_set(stats_key, "2")
             .expect("Failed to set stats_key to 2.");
@@ -242,6 +244,12 @@ fn solve(
                 if let Some(m) = get_model(tman_config, model, &mut is_usable) {
                     if is_usable {
                         usable_model = Some(m);
+
+                        // Clingo will only output increasingly optimized
+                        // models, so we need to take the last model without an
+                        // error statement from all outputted models, not just
+                        // the first good one. Therefore, we shouldn’t break
+                        // here.
                     } else {
                         non_usable_models.push(m); // Collect error models.
                     }