Skip to content

Commit 785fd8f

Browse files
MizuxMizux
committed
cpp: improve doc
1 parent b67dc02 commit 785fd8f

File tree

3 files changed

+78
-80
lines changed

3 files changed

+78
-80
lines changed

‎ortools/constraint_solver/constraint_solver.h‎

Lines changed: 42 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -12,47 +12,47 @@
1212
// limitations under the License.
1313

1414
/** @file constraint_solver.h
15-
* Declaration of the core objects for the constraint solver.
16-
*
17-
* The literature around constraint programming is extremely dense but one
18-
* can find some basic introductions in the following links:
19-
* - http://en.wikipedia.org/wiki/Constraint_programming
20-
* - http://kti.mff.cuni.cz/~bartak/constraints/index.html
21-
*
22-
* Here is a very simple Constraint Programming problem:
23-
*
24-
* If we see 56 legs and 20 heads, how many two-legged pheasants
25-
* and four-legged rabbits are we looking at?
26-
*
27-
* Here is some simple Constraint Programming code to find out:
28-
* @code{.cpp}
29-
* void pheasant() {
30-
* Solver s("pheasant");
31-
* // Create integer variables to represent the number of pheasants and
32-
* // rabbits, with a minimum of 0 and a maximum of 20.
33-
* IntVar* const p = s.MakeIntVar(0, 20, "pheasant"));
34-
* IntVar* const r = s.MakeIntVar(0, 20, "rabbit"));
35-
* // The number of heads is the sum of pheasants and rabbits.
36-
* IntExpr* const heads = s.MakeSum(p, r);
37-
* // The number of legs is the sum of pheasants * 2 and rabbits * 4.
38-
* IntExpr* const legs = s.MakeSum(s.MakeProd(p, 2), s.MakeProd(r, 4));
39-
* // Constraints: the number of legs is 56 and heads is 20.
40-
* Constraint* const ct_legs = s.MakeEquality(legs, 56);
41-
* Constraint* const ct_heads = s.MakeEquality(heads, 20);
42-
* s.AddConstraint(ct_legs);
43-
* s.AddConstraint(ct_heads);
44-
* DecisionBuilder* const db = s.MakePhase(p, r,
45-
* Solver::CHOOSE_FIRST_UNBOUND,
46-
* Solver::ASSIGN_MIN_VALUE);
47-
* s.NewSearch(db);
48-
* CHECK(s.NextSolution());
49-
* LOG(INFO) << "rabbits -> " << r->Value() << ", pheasants -> "
50-
* << p->Value();
51-
* LOG(INFO) << s.DebugString();
52-
* s.EndSearch();
53-
* }
54-
* @endcode
55-
* which outputs:
15+
Declaration of the core objects for the constraint solver.
16+
17+
The literature around constraint programming is extremely dense but one
18+
can find some basic introductions in the following links:
19+
- http://en.wikipedia.org/wiki/Constraint_programming
20+
- http://kti.mff.cuni.cz/~bartak/constraints/index.html
21+
22+
Here is a very simple Constraint Programming problem:
23+
24+
If we see 56 legs and 20 heads, how many two-legged pheasants
25+
and four-legged rabbits are we looking at?
26+
27+
Here is some simple Constraint Programming code to find out:
28+
@code{.cpp}
29+
void pheasant() {
30+
Solver s("pheasant");
31+
// Create integer variables to represent the number of pheasants and
32+
// rabbits, with a minimum of 0 and a maximum of 20.
33+
IntVar* const p = s.MakeIntVar(0, 20, "pheasant"));
34+
IntVar* const r = s.MakeIntVar(0, 20, "rabbit"));
35+
// The number of heads is the sum of pheasants and rabbits.
36+
IntExpr* const heads = s.MakeSum(p, r);
37+
// The number of legs is the sum of pheasants * 2 and rabbits * 4.
38+
IntExpr* const legs = s.MakeSum(s.MakeProd(p, 2), s.MakeProd(r, 4));
39+
// Constraints: the number of legs is 56 and heads is 20.
40+
Constraint* const ct_legs = s.MakeEquality(legs, 56);
41+
Constraint* const ct_heads = s.MakeEquality(heads, 20);
42+
s.AddConstraint(ct_legs);
43+
s.AddConstraint(ct_heads);
44+
DecisionBuilder* const db = s.MakePhase(p, r,
45+
Solver::CHOOSE_FIRST_UNBOUND,
46+
Solver::ASSIGN_MIN_VALUE);
47+
s.NewSearch(db);
48+
CHECK(s.NextSolution());
49+
LOG(INFO) << "rabbits -> " << r->Value() << ", pheasants -> "
50+
<< p->Value();
51+
LOG(INFO) << s.DebugString();
52+
s.EndSearch();
53+
}
54+
@endcode
55+
which outputs:
5656
@verbatim
5757
rabbits -> 8, pheasants -> 12
5858
Solver(name = "pheasant",
@@ -1034,7 +1034,7 @@ class Solver {
10341034
/// are relative to this time.
10351035
absl::Time Now() const;
10361036

1037-
/// DEPRECATED: Use Now() instead.
1037+
/// @deprecated Use Now() instead.
10381038
/// Time elapsed, in ms since the creation of the solver.
10391039
int64_t wall_time() const;
10401040

‎ortools/constraint_solver/constraint_solveri.h‎

Lines changed: 31 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -12,40 +12,37 @@
1212
// limitations under the License.
1313

1414
/** @file constraint_solveri.h
15-
* Collection of objects used to extend the Constraint Solver library.
16-
*
17-
* This file contains a set of objects that simplifies writing extensions
18-
* of the library.
19-
*
20-
* The main objects that define extensions are:
21-
* - BaseIntExpr, the base class of all expressions that are not variables.
22-
* - SimpleRevFIFO, a reversible FIFO list with templatized values.
23-
* A reversible data structure is a data structure that reverts its
24-
* modifications when the search is going up in the search tree, usually
25-
* after a failure occurs.
26-
* - RevImmutableMultiMap, a reversible immutable multimap.
27-
* - MakeConstraintDemon<n> and MakeDelayedConstraintDemon<n> to wrap methods
28-
* of a constraint as a demon.
29-
* - RevSwitch, a reversible flip-once switch.
30-
* - SmallRevBitSet, RevBitSet, and RevBitMatrix: reversible 1D or 2D
31-
* bitsets.
32-
* - LocalSearchOperator, IntVarLocalSearchOperator, ChangeValue and
33-
* PathOperator, to create new local search operators.
34-
* - LocalSearchFilter and IntVarLocalSearchFilter, to create new local
35-
* search filters.
36-
* - BaseLns, to write Large Neighborhood Search operators.
37-
* - SymmetryBreaker, to describe model symmetries that will be broken during
38-
* search using the 'Symmetry Breaking During Search' framework
39-
* see Gent, I. P., Harvey, W., & Kelsey, T. (2002).
40-
* Groups and Constraints: Symmetry Breaking During Search.
41-
* Principles and Practice of Constraint Programming CP2002
42-
* (Vol. 2470, pp. 415-430). Springer. Retrieved from
43-
* http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.11.1442.
44-
*
45-
* Then, there are some internal classes that are used throughout the solver
46-
* and exposed in this file:
47-
* - SearchLog, the root class of all periodic outputs during search.
48-
* - ModelCache, A caching layer to avoid creating twice the same object.
15+
Collection of objects used to extend the Constraint Solver library.
16+
This file contains a set of objects that simplifies writing extensions
17+
of the library.
18+
The main objects that define extensions are:
19+
- BaseIntExpr, the base class of all expressions that are not variables.
20+
- SimpleRevFIFO, a reversible FIFO list with templatized values.
21+
A reversible data structure is a data structure that reverts its
22+
modifications when the search is going up in the search tree, usually
23+
after a failure occurs.
24+
- RevImmutableMultiMap, a reversible immutable multimap.
25+
- MakeConstraintDemon<n> and MakeDelayedConstraintDemon<n> to wrap methods
26+
of a constraint as a demon.
27+
- RevSwitch, a reversible flip-once switch.
28+
- SmallRevBitSet, RevBitSet, and RevBitMatrix: reversible 1D or 2D
29+
bitsets.
30+
- LocalSearchOperator, IntVarLocalSearchOperator, ChangeValue and
31+
PathOperator, to create new local search operators.
32+
- LocalSearchFilter and IntVarLocalSearchFilter, to create new local
33+
search filters.
34+
- BaseLns, to write Large Neighborhood Search operators.
35+
- SymmetryBreaker, to describe model symmetries that will be broken during
36+
search using the 'Symmetry Breaking During Search' framework
37+
see Gent, I. P., Harvey, W., & Kelsey, T. (2002).
38+
Groups and Constraints: Symmetry Breaking During Search.
39+
Principles and Practice of Constraint Programming CP2002
40+
(Vol. 2470, pp. 415-430). Springer. Retrieved from
41+
http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.11.1442.
42+
Then, there are some internal classes that are used throughout the solver
43+
and exposed in this file:
44+
- SearchLog, the root class of all periodic outputs during search.
45+
- ModelCache, A caching layer to avoid creating twice the same object.
4946
*/
5047

5148
#ifndef ORTOOLS_CONSTRAINT_SOLVER_CONSTRAINT_SOLVERI_H_

‎ortools/linear_solver/linear_solver.h‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -865,9 +865,10 @@ class MPSolver {
865865
static int64_t global_num_variables();
866866
static int64_t global_num_constraints();
867867

868-
// DEPRECATED: Use TimeLimit() and SetTimeLimit(absl::Duration) instead.
869-
// NOTE: These deprecated functions used the convention time_limit = 0 to mean
870-
// "no limit", which now corresponds to time_limit_ = InfiniteDuration().
868+
/// @deprecated Use TimeLimit() and SetTimeLimit(absl::Duration) instead.
869+
/// @note These deprecated functions used the convention `time_limit = 0`
870+
/// to mean "no limit", which now corresponds
871+
/// `to time_limit_ = InfiniteDuration()`.
871872
int64_t time_limit() const {
872873
return time_limit_ == absl::InfiniteDuration()
873874
? 0
@@ -882,7 +883,7 @@ class MPSolver {
882883
return static_cast<double>(time_limit()) / 1000.0;
883884
}
884885

885-
// DEPRECATED: Use DurationSinceConstruction() instead.
886+
/// @deprecated Use DurationSinceConstruction() instead.
886887
int64_t wall_time() const {
887888
return absl::ToInt64Milliseconds(DurationSinceConstruction());
888889
}

0 commit comments

Comments
 (0)