From 785fd8fde0a78921f25bec8f87d346d094c4b6c7 Mon Sep 17 00:00:00 2001 From: Corentin Le Molgat Date: Wed, 12 Nov 2025 14:11:31 +0100 Subject: [PATCH] cpp: improve doc --- ortools/constraint_solver/constraint_solver.h | 84 +++++++++---------- .../constraint_solver/constraint_solveri.h | 65 +++++++------- ortools/linear_solver/linear_solver.h | 9 +- 3 files changed, 78 insertions(+), 80 deletions(-) diff --git a/ortools/constraint_solver/constraint_solver.h b/ortools/constraint_solver/constraint_solver.h index 56af82927d..1907ca4f9d 100644 --- a/ortools/constraint_solver/constraint_solver.h +++ b/ortools/constraint_solver/constraint_solver.h @@ -12,47 +12,47 @@ // limitations under the License. /** @file constraint_solver.h -* Declaration of the core objects for the constraint solver. -* -* The literature around constraint programming is extremely dense but one -* can find some basic introductions in the following links: -* - http://en.wikipedia.org/wiki/Constraint_programming -* - http://kti.mff.cuni.cz/~bartak/constraints/index.html -* -* Here is a very simple Constraint Programming problem: -* -* If we see 56 legs and 20 heads, how many two-legged pheasants -* and four-legged rabbits are we looking at? -* -* Here is some simple Constraint Programming code to find out: -* @code{.cpp} -* void pheasant() { -* Solver s("pheasant"); -* // Create integer variables to represent the number of pheasants and -* // rabbits, with a minimum of 0 and a maximum of 20. -* IntVar* const p = s.MakeIntVar(0, 20, "pheasant")); -* IntVar* const r = s.MakeIntVar(0, 20, "rabbit")); -* // The number of heads is the sum of pheasants and rabbits. -* IntExpr* const heads = s.MakeSum(p, r); -* // The number of legs is the sum of pheasants * 2 and rabbits * 4. -* IntExpr* const legs = s.MakeSum(s.MakeProd(p, 2), s.MakeProd(r, 4)); -* // Constraints: the number of legs is 56 and heads is 20. -* Constraint* const ct_legs = s.MakeEquality(legs, 56); -* Constraint* const ct_heads = s.MakeEquality(heads, 20); -* s.AddConstraint(ct_legs); -* s.AddConstraint(ct_heads); -* DecisionBuilder* const db = s.MakePhase(p, r, -* Solver::CHOOSE_FIRST_UNBOUND, -* Solver::ASSIGN_MIN_VALUE); -* s.NewSearch(db); -* CHECK(s.NextSolution()); -* LOG(INFO) << "rabbits -> " << r->Value() << ", pheasants -> " -* << p->Value(); -* LOG(INFO) << s.DebugString(); -* s.EndSearch(); -* } -* @endcode -* which outputs: +Declaration of the core objects for the constraint solver. + +The literature around constraint programming is extremely dense but one +can find some basic introductions in the following links: + - http://en.wikipedia.org/wiki/Constraint_programming + - http://kti.mff.cuni.cz/~bartak/constraints/index.html + +Here is a very simple Constraint Programming problem: + + If we see 56 legs and 20 heads, how many two-legged pheasants + and four-legged rabbits are we looking at? + +Here is some simple Constraint Programming code to find out: +@code{.cpp} + void pheasant() { + Solver s("pheasant"); + // Create integer variables to represent the number of pheasants and + // rabbits, with a minimum of 0 and a maximum of 20. + IntVar* const p = s.MakeIntVar(0, 20, "pheasant")); + IntVar* const r = s.MakeIntVar(0, 20, "rabbit")); + // The number of heads is the sum of pheasants and rabbits. + IntExpr* const heads = s.MakeSum(p, r); + // The number of legs is the sum of pheasants * 2 and rabbits * 4. + IntExpr* const legs = s.MakeSum(s.MakeProd(p, 2), s.MakeProd(r, 4)); + // Constraints: the number of legs is 56 and heads is 20. + Constraint* const ct_legs = s.MakeEquality(legs, 56); + Constraint* const ct_heads = s.MakeEquality(heads, 20); + s.AddConstraint(ct_legs); + s.AddConstraint(ct_heads); + DecisionBuilder* const db = s.MakePhase(p, r, + Solver::CHOOSE_FIRST_UNBOUND, + Solver::ASSIGN_MIN_VALUE); + s.NewSearch(db); + CHECK(s.NextSolution()); + LOG(INFO) << "rabbits -> " << r->Value() << ", pheasants -> " + << p->Value(); + LOG(INFO) << s.DebugString(); + s.EndSearch(); + } +@endcode +which outputs: @verbatim rabbits -> 8, pheasants -> 12 Solver(name = "pheasant", @@ -1034,7 +1034,7 @@ class Solver { /// are relative to this time. absl::Time Now() const; - /// DEPRECATED: Use Now() instead. + /// @deprecated Use Now() instead. /// Time elapsed, in ms since the creation of the solver. int64_t wall_time() const; diff --git a/ortools/constraint_solver/constraint_solveri.h b/ortools/constraint_solver/constraint_solveri.h index 29a5e6a40e..c63d2219fd 100644 --- a/ortools/constraint_solver/constraint_solveri.h +++ b/ortools/constraint_solver/constraint_solveri.h @@ -12,40 +12,37 @@ // limitations under the License. /** @file constraint_solveri.h -* Collection of objects used to extend the Constraint Solver library. -* -* This file contains a set of objects that simplifies writing extensions -* of the library. -* -* The main objects that define extensions are: -* - BaseIntExpr, the base class of all expressions that are not variables. -* - SimpleRevFIFO, a reversible FIFO list with templatized values. -* A reversible data structure is a data structure that reverts its -* modifications when the search is going up in the search tree, usually -* after a failure occurs. -* - RevImmutableMultiMap, a reversible immutable multimap. -* - MakeConstraintDemon and MakeDelayedConstraintDemon to wrap methods -* of a constraint as a demon. -* - RevSwitch, a reversible flip-once switch. -* - SmallRevBitSet, RevBitSet, and RevBitMatrix: reversible 1D or 2D -* bitsets. -* - LocalSearchOperator, IntVarLocalSearchOperator, ChangeValue and -* PathOperator, to create new local search operators. -* - LocalSearchFilter and IntVarLocalSearchFilter, to create new local -* search filters. -* - BaseLns, to write Large Neighborhood Search operators. -* - SymmetryBreaker, to describe model symmetries that will be broken during -* search using the 'Symmetry Breaking During Search' framework -* see Gent, I. P., Harvey, W., & Kelsey, T. (2002). -* Groups and Constraints: Symmetry Breaking During Search. -* Principles and Practice of Constraint Programming CP2002 -* (Vol. 2470, pp. 415-430). Springer. Retrieved from -* http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.11.1442. -* -* Then, there are some internal classes that are used throughout the solver -* and exposed in this file: -* - SearchLog, the root class of all periodic outputs during search. -* - ModelCache, A caching layer to avoid creating twice the same object. +Collection of objects used to extend the Constraint Solver library. +This file contains a set of objects that simplifies writing extensions +of the library. +The main objects that define extensions are: + - BaseIntExpr, the base class of all expressions that are not variables. + - SimpleRevFIFO, a reversible FIFO list with templatized values. + A reversible data structure is a data structure that reverts its + modifications when the search is going up in the search tree, usually + after a failure occurs. + - RevImmutableMultiMap, a reversible immutable multimap. + - MakeConstraintDemon and MakeDelayedConstraintDemon to wrap methods + of a constraint as a demon. + - RevSwitch, a reversible flip-once switch. + - SmallRevBitSet, RevBitSet, and RevBitMatrix: reversible 1D or 2D + bitsets. + - LocalSearchOperator, IntVarLocalSearchOperator, ChangeValue and + PathOperator, to create new local search operators. + - LocalSearchFilter and IntVarLocalSearchFilter, to create new local + search filters. + - BaseLns, to write Large Neighborhood Search operators. + - SymmetryBreaker, to describe model symmetries that will be broken during + search using the 'Symmetry Breaking During Search' framework + see Gent, I. P., Harvey, W., & Kelsey, T. (2002). + Groups and Constraints: Symmetry Breaking During Search. + Principles and Practice of Constraint Programming CP2002 + (Vol. 2470, pp. 415-430). Springer. Retrieved from + http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.11.1442. +Then, there are some internal classes that are used throughout the solver +and exposed in this file: + - SearchLog, the root class of all periodic outputs during search. + - ModelCache, A caching layer to avoid creating twice the same object. */ #ifndef ORTOOLS_CONSTRAINT_SOLVER_CONSTRAINT_SOLVERI_H_ diff --git a/ortools/linear_solver/linear_solver.h b/ortools/linear_solver/linear_solver.h index a6729ff753..165b0a0187 100644 --- a/ortools/linear_solver/linear_solver.h +++ b/ortools/linear_solver/linear_solver.h @@ -865,9 +865,10 @@ class MPSolver { static int64_t global_num_variables(); static int64_t global_num_constraints(); - // DEPRECATED: Use TimeLimit() and SetTimeLimit(absl::Duration) instead. - // NOTE: These deprecated functions used the convention time_limit = 0 to mean - // "no limit", which now corresponds to time_limit_ = InfiniteDuration(). + /// @deprecated Use TimeLimit() and SetTimeLimit(absl::Duration) instead. + /// @note These deprecated functions used the convention `time_limit = 0` + /// to mean "no limit", which now corresponds + /// `to time_limit_ = InfiniteDuration()`. int64_t time_limit() const { return time_limit_ == absl::InfiniteDuration() ? 0 @@ -882,7 +883,7 @@ class MPSolver { return static_cast(time_limit()) / 1000.0; } - // DEPRECATED: Use DurationSinceConstruction() instead. + /// @deprecated Use DurationSinceConstruction() instead. int64_t wall_time() const { return absl::ToInt64Milliseconds(DurationSinceConstruction()); }