cpp: improve doc

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;
 

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<n> and MakeDelayedConstraintDemon<n> 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<n> and MakeDelayedConstraintDemon<n> 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_

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<double>(time_limit()) / 1000.0;
   }
 
-  // DEPRECATED: Use DurationSinceConstruction() instead.
+  /// @deprecated Use DurationSinceConstruction() instead.
   int64_t wall_time() const {
     return absl::ToInt64Milliseconds(DurationSinceConstruction());
   }