Tighten solution comparison documentation

Author: zayenz

changelog.in

@@ -101,17 +101,14 @@ Module: search
 What:   change
 Rank:   major
 [DESCRIPTION]
-Best-solution search now uses Space::compare() when choosing between
-independently produced solutions, including external incumbents and portfolio
-assets. Optimization spaces with a custom objective must override compare() as
-well as constrain(). compare() ranks solutions without changing them;
-constrain() still posts improvement restrictions. Comparability is defined by
-the model. The built-in floating-point models compare their documented
-objective bounds, independently of the improvement step. Current exact engines
-reject incomparable incoming solutions. A future best-effort policy could
-instead make an incomparable incoming solution current best, without changing
-the comparison interface, but that would not by itself guarantee completeness
-or maximality. Adding the virtual comparison function changes the C++ ABI of
+Best-solution search uses Space::compare() to choose between independently
+produced solutions, including external incumbents and portfolio assets.
+Optimization spaces with a custom objective must override compare() as well as
+constrain(). compare() ranks solutions without changing them; constrain() posts
+improvement restrictions. The model defines comparability. Built-in
+floating-point models compare their documented objective bounds independently
+of the improvement step. Current exact engines reject incomparable incoming
+solutions. Adding the virtual comparison function changes the C++ ABI of
 Space.
 
 [RELEASE]

gecode/flatzinc.hh

@@ -630,9 +630,10 @@ namespace Gecode { namespace FlatZinc {
      * \brief Compare compatible optimization objectives
      *
      * Integer objectives compare assigned values. Float objectives require
-     * the same direction and step, and assigned (possibly adjacent-endpoint)
-     * intervals. Float minimization ranks lower endpoints and maximization
-     * ranks upper endpoints, independently of the step used by constrain().
+     * the same direction and step, and assigned intervals, which may span
+     * adjacent float values. Float minimization ranks lower endpoints and
+     * maximization ranks upper endpoints, independently of the step used by
+     * constrain().
      */
     virtual SpaceComparison compare(const Space& s) const;
     /// Compare this space with space \a s and print the differences on

gecode/kernel/core.hpp

@@ -56,8 +56,8 @@ namespace Gecode {
   /**
    * \brief Result of comparing two spaces according to their objectives
    *
-   * Adding Space::compare changes the ordinary C++ ABI of Space by extending
-   * its virtual function table.
+   * Space::compare extends Space's virtual function table and changes its
+   * C++ ABI.
    */
   enum SpaceComparison {
     SC_BETTER,     ///< The receiver has a better objective
@@ -2102,19 +2102,16 @@ namespace Gecode {
     /**
      * \brief Compare this space's objective with \a other
      *
-     * The comparison is read-only and receiver-relative. Implementations may
-     * require objective information sufficient for the relation they report.
-     * The model owns this readiness rule: comparison does not require every
-     * objective variable to be assigned when the model can establish a sound
-     * result from the available information.
+     * The comparison is read-only and receiver-relative. The model defines
+     * the objective information needed for a sound result; not every objective
+     * variable must be assigned.
      * The default implementation throws SpaceNoComparison.
      * SC_INCOMPARABLE is a model-defined ordering result, not missing
      * information. Current exact best-solution engines reject it.
      *
      * Optimization models overriding constrain with a different objective
-     * must also override compare.
-     * constrain remains responsible for posting improvement restrictions;
-     * search does not use it to rank two solutions.
+     * must also override compare. constrain posts improvement restrictions;
+     * search uses compare to rank solutions.
      *
      * Exact best-solution search requires SC_BETTER to be irreflexive and
      * transitive, SC_WORSE to be its reverse, and SC_EQUIVALENT to be
@@ -2130,13 +2127,13 @@ namespace Gecode {
      * float optimization spaces compare the incumbent bound used by their
      * cuts: the upper bound for minimization and lower bound for maximization.
      * This ranking is independent of the step used for approximate cuts.
-     * FlatZinc retains its interval-valued cuts and instead ranks the lower
-     * bound for minimization and upper bound for maximization.
+     * FlatZinc uses interval-valued cuts and ranks the lower bound for
+     * minimization and upper bound for maximization.
      *
      * After compare throws during BAB, PBS, or RBS search, destroy and
      * recreate the public search engine. An internal engine interface that
      * explicitly supports reset can establish a new search after failure;
-     * other post-exception use has no recovery guarantee.
+     * other use after an exception has no recovery guarantee.
      */
     GECODE_KERNEL_EXPORT virtual SpaceComparison
     compare(const Space& other) const;

gecode/search.hh

@@ -1157,11 +1157,10 @@ namespace Gecode {
   /**
    * \brief Depth-first branch-and-bound search engine
    *
-   * Additionally, \a s must implement Space::constrain and Space::compare.
-   * Whenever exploration requires to add a constraint
-   * to the space \a c currently being explored, the engine
-   * executes \c c.constrain(t) where \a t is the so-far
-   * best solution.
+   * Space \a s must implement Space::constrain and Space::compare.
+   * When exploration needs an improvement constraint, the engine calls
+   * \c c.constrain(t) on the current space \a c, where \a t is the best
+   * solution found so far.
    * See Space::compare for the ordering and pruning requirements. If objective
    * comparison throws, destroy the engine; only an internal engine interface
    * that explicitly supports reset can establish a new search after failure.
@@ -1179,13 +1178,12 @@ namespace Gecode {
   /**
    * \brief Perform depth-first branch-and-bound search for subclass \a T of space \a s and options \a o
    *
-   * Additionally, \a s must implement Space::constrain and Space::compare.
-   * Whenever exploration requires to add a constraint
-   * to the space \a c currently being explored, the engine
-   * executes \c c.constrain(t) where \a t is the so-far
-   * best solution.
+   * Space \a s must implement Space::constrain and Space::compare.
+   * When exploration needs an improvement constraint, the engine calls
+   * \c c.constrain(t) on the current space \a c, where \a t is the best
+   * solution found so far.
    * See Space::compare for the ordering and pruning requirements. If objective
-   * comparison throws, destroy the engine rather than continuing to use it.
+   * comparison throws, destroy and recreate the engine.
    *
    * \ingroup TaskModelSearch
    */