Update doc (#37)

* Doc for usual constraint.

* Some doc improvement

* Some doc improvement 2/?

* Some doc improvement 3/?

* Some doc improvement 4/?

* Some doc improvement 5/?

* Improves the doc

* tag new version and CI

Author: Azzaare

.github/workflows/ci.yml

@@ -9,7 +9,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - "1.9"
+          - "1.10"
           - 'nightly'
         os:
           - ubuntu-latest

Project.toml

@@ -1,7 +1,7 @@
 name = "Constraints"
 uuid = "30f324ab-b02d-43f0-b619-e131c61659f7"
 authors = ["Jean-François Baffier"]
-version = "0.5.3"
+version = "0.5.4"
 
 [deps]
 CompositionalNetworks = "4b67e4b5-442d-4ef5-b760-3f5df3a57537"
@@ -19,7 +19,7 @@ CompositionalNetworks = "0.5"
 ConstraintCommons = "0.1"
 ConstraintDomains = "0.3"
 DataFrames = "1"
-Dictionaries = "0.3"
+Dictionaries = "0.4"
 MacroTools = "0.5"
 PrettyTables = "2"
 TestItemRunner = "0.2"

src/Constraints.jl

@@ -39,7 +39,7 @@ include("constraint.jl")
 include("usual_constraints.jl")
 
 # SECTION - Generic Constraints: intension, extension
-include("constraints/intention.jl")
+include("constraints/intension.jl")
 include("constraints/extension.jl")
 
 # SECTION - Constraints defined from Languages

src/constraint.jl

@@ -72,6 +72,24 @@ Return the list of symmetries of `c`.
 """
 symmetries(c::Constraint) = c.symmetries
 
+"""
+    make_error(symb::Symbol)
+
+Create a function that returns an error based on the predicate of the constraint identified by the symbol provided.
+
+## Arguments
+- `symb::Symbol`: The symbol used to determine the error function to be returned. The function first checks if a predicate with the prefix "icn_" exists in the Constraints module. If it does, it returns that function. If it doesn't, it checks for a predicate with the prefix "error_". If that exists, it returns that function. If neither exists, it returns a function that evaluates the predicate with the prefix "concept_" and returns the negation of its result cast to Float64.
+
+## Returns
+- Function: A function that takes in a variable `x` and an arbitrary number of parameters `params`. The function returns a Float64.
+
+# Examples
+```julia
+e = make_error(:all_different)
+e([1, 2, 3]) # Returns 0.0
+e([1, 1, 3]) # Returns 1.0
+```
+"""
 function make_error(symb::Symbol)
     isdefined(Constraints, Symbol("icn_$symb")) && (return eval(Symbol("icn_$symb")))
     isdefined(Constraints, Symbol("error_$symb")) && (return eval(Symbol("error_$symb")))
@@ -85,6 +103,25 @@ Simply delete the `concept_` part of symbol or string starting with it. TODO: ad
 """
 shrink_concept(s) = Symbol(string(s)[9:end])
 
+"""
+    concept_vs_error(c, e, args...; kargs...)
+
+Compare the results of a concept function and an error function for the same inputs. It is mainly used for testing purposes.
+
+# Arguments
+- `c`: The concept function.
+- `e`: The error function.
+- `args...`: Positional arguments to be passed to both the concept and error functions.
+- `kargs...`: Keyword arguments to be passed to both the concept and error functions.
+
+# Returns
+- Boolean: Returns true if the result of the concept function is not equal to whether the result of the error function is greater than 0.0. Otherwise, it returns false.
+
+# Examples
+```julia
+concept_vs_error(all_different, make_error(:all_different), [1, 2, 3]) # Returns false
+```
+"""
 function concept_vs_error(c, e, args...; kargs...)
     return c(args...; kargs...) ≠ (e(args...; kargs...) > 0.0)
 end

src/constraints/all_different.jl

@@ -1,5 +1,34 @@
 #!SECTION - all_different
 
+const description_all_different = """
+    Global constraint ensuring that all the values of `x` are all different.
+"""
+
+"""
+    xcsp_all_different(list::Vector{Int})
+
+Return `true` if all the values of `list` are different, `false` otherwise.
+
+## Arguments
+- `list::Vector{Int}`: list of values to check.
+
+## Variants
+- `:all_different`: $description_all_different
+```julia
+concept(:all_different, x; vals)
+concept(:all_different)(x; vals)
+```
+
+## Examples
+```julia
+c = concept(:all_different)
+
+c([1, 2, 3, 4])
+c([1, 2, 3, 1])
+c([1, 0, 0, 4]; vals=[0])
+c([1, 0, 0, 1]; vals=[0])
+```
+"""
 xcsp_all_different(list, ::Nothing) = allunique(list)
 
 function xcsp_all_different(list, except)
@@ -8,8 +37,6 @@ end
 
 xcsp_all_different(; list, except=nothing) = xcsp_all_different(list, except)
 
-const description_all_different = """Global constraint ensuring that all the values of a given configuration are unique"""
-
 @usual concept_all_different(x; vals=nothing) = xcsp_all_different(list=x, except=vals)
 
 ## SECTION - Test Items

src/constraints/all_equal.jl

@@ -1,9 +1,39 @@
 #!SECTION - all_equal
 
-const description_all_equal = """Global constraint ensuring that all the values of `x` are all equal"""
+const description_all_equal = """
+    Global constraint ensuring that all the values of `x` are all equal.
+"""
 
 concept_all_equal(x, val) = all(y -> y == val, x)
 
+"""
+    xcsp_all_equal(list::Vector{Int}, val::Int)
+
+Return `true` if all the values of `list` are equal to `val`, `false` otherwise.
+
+## Arguments
+- `list::Vector{Int}`: list of values to check.
+- `val::Int`: value to compare to.
+
+## Variants
+- `:all_equal`: $description_all_equal
+```julia
+concept(:all_equal, x; val=nothing, pair_vars=zeros(x), op=+)
+concept(:all_equal)(x; val=nothing, pair_vars=zeros(x), op=+)
+```
+
+## Examples
+```julia
+c = concept(:all_equal)
+
+c([0, 0, 0, 0])
+c([1, 2, 3, 4])
+c([3, 2, 1, 0]; pair_vars=[0, 1, 2, 3])
+c([0, 1, 2, 3]; pair_vars=[0, 1, 2, 3])
+c([1, 2, 3, 4]; op=/, val=1, pair_vars=[1, 2, 3, 4])
+c([1, 2, 3, 4]; op=*, val=1, pair_vars=[1, 2, 3, 4])
+```
+"""
 xcsp_all_equal(; list) = concept_all_equal(list; val=first(list))
 
 @usual function concept_all_equal(x; val=nothing, pair_vars=zero(x), op=+)

src/constraints/cardinality.jl

@@ -1,9 +1,64 @@
 # cardinality (or global_cardinality or gcc)
 
-const description_cardinality = """Global constraint ensuring that all ...`"""
-const description_cardinality_closed = """Global constraint ensuring that all ...`"""
-const description_cardinality_open = """Global constraint ensuring that all ...`"""
+const description_cardinality = """
+The cardinality constraint, also known as the global cardinality constraint (GCC), is a constraint in constraint programming that restricts the number of times a value can appear in a set of variables.
+"""
+const description_cardinality_closed = """
+The closed cardinality constraint, also known as the global cardinality constraint (GCC), is a constraint in constraint programming that restricts the number of times a value can appear in a set of variables. It is closed, meaning that all values in the domain of the variables must be considered.
+"""
 
+const description_cardinality_open = """
+The open cardinality constraint, also known as the global cardinality constraint (GCC), is a constraint in constraint programming that restricts the number of times a value can appear in a set of variables. It is open, meaning that only the values in the list of values must be considered.
+"""
+
+"""
+    xcsp_cardinality(list, values, occurs, closed)
+
+Return `true` if the number of occurrences of the values in `values` in `list` satisfies the given condition, `false` otherwise.
+
+## Arguments
+- `list::Vector{Int}`: list of values to check.
+- `values::Vector{Int}`: list of values to check.
+- `occurs::Vector{Int}`: list of occurrences to check.
+- `closed::Bool`: whether the constraint is closed or not.
+
+## Variants
+- `:cardinality`: $description_cardinality
+```julia
+concept(:cardinality, x; bool=false, vals)
+concept(:cardinality)(x; bool=false, vals)
+```
+- `:cardinality_closed`: $description_cardinality_closed
+```julia
+concept(:cardinality_closed, x; vals)
+concept(:cardinality_closed)(x; vals)
+```
+- `:cardinality_open`: $description_cardinality_open
+```julia
+concept(:cardinality_open, x; vals)
+concept(:cardinality_open)(x; vals)
+```
+
+## Examples
+```julia
+c = concept(:cardinality)
+
+c([2, 5, 10, 10]; vals=[2 0 1; 5 1 3; 10 2 3])
+c([8, 5, 10, 10]; vals=[2 0 1; 5 1 3; 10 2 3], bool=false)
+c([8, 5, 10, 10]; vals=[2 0 1; 5 1 3; 10 2 3], bool=true)
+c([2, 5, 10, 10]; vals=[2 1; 5 1; 10 2])
+c([2, 5, 10, 10]; vals=[2 0 1 42; 5 1 3 7; 10 2 3 -4])
+c([2, 5, 5, 10]; vals=[2 0 1; 5 1 3; 10 2 3])
+c([2, 5, 10, 8]; vals=[2 1; 5 1; 10 2])
+c([5, 5, 5, 10]; vals=[2 0 1 42; 5 1 3 7; 10 2 3 -4])
+
+cc = concept(:cardinality_closed)
+cc([8, 5, 10, 10]; vals=[2 0 1; 5 1 3; 10 2 3])
+
+co = concept(:cardinality_open)
+co([8, 5, 10, 10]; vals=[2 0 1; 5 1 3; 10 2 3])
+```
+"""
 function xcsp_cardinality(; list, values, occurs, closed=false)
     counts = zeros(Int, Indices(distinct(values)))
     for t in list

src/constraints/channel.jl

@@ -1,3 +1,35 @@
+const description = """
+The channel constraint establishes a bijective correspondence between two sets of variables. This means that each value in the first set of variables corresponds to a unique value in the second set, and vice versa.
+"""
+
+"""
+    xcsp_channel(; list)
+
+Return `true` if the channel constraint is satisfied, `false` otherwise. The channel constraint establishes a bijective correspondence between two sets of variables. This means that each value in the first set of variables corresponds to a unique value in the second set, and vice versa.
+
+## Arguments
+- `list::Union{AbstractVector, Tuple}`: list of values to check.
+
+## Variants
+- `:channel`: $description
+```julia
+concept(:channel, x; dim=1, id=nothing)
+concept(:channel)(x; dim=1, id=nothing)
+```
+
+## Examples
+```julia
+c = concept(:channel)
+
+c([2, 1, 4, 3])
+c([1, 2, 3, 4])
+c([2, 3, 1, 4])
+c([2, 1, 5, 3, 4, 2, 1, 4, 5, 3]; dim=2)
+c([2, 1, 4, 3, 5, 2, 1, 4, 5, 3]; dim=2)
+c([false, false, true, false]; id=3)
+c([false, false, true, false]; id=1)
+```
+"""
 function xcsp_channel(list::AbstractVector)
     for (i, j) in enumerate(list)
         if i ≤ j
@@ -32,8 +64,6 @@ end
 
 concept_channel(x, ::Val) = xcsp_channel(list=x)
 
-const description_channel = """Global constraint ensuring that all ...`"""
-
 concept_channel(x, id) = count(!iszero, x) == 1 == x[id]
 
 @usual function concept_channel(x; dim=1, id = nothing)

src/constraints/circuit.jl

@@ -1,3 +1,33 @@
+const description_circuit = """
+The circuit constraint is a global constraint used in constraint programming, often in routing problems. It ensures that the values of a list of variables form a circuit, i.e., a sequence where each value is the index of the next value in the sequence, and the sequence eventually loops back to the start.
+"""
+
+"""
+    xcsp_circuit(; list, size)
+
+Return `true` if the circuit constraint is satisfied, `false` otherwise. The circuit constraint is a global constraint used in constraint programming, often in routing problems. It ensures that the values of a list of variables form a circuit, i.e., a sequence where each value is the index of the next value in the sequence, and the sequence eventually loops back to the start.
+
+## Arguments
+- `list::AbstractVector`: list of values to check.
+- `size::Int`: size of the circuit.
+
+## Variants
+- `:circuit`: $description_circuit
+```julia
+concept(:circuit, x; op, val)
+concept(:circuit)(x; op, val)
+```
+
+## Examples
+```julia
+c = concept(:circuit)
+
+c([1, 2, 3, 4])
+c([2, 3, 4, 1])
+c([2, 3, 1, 4]; op = ==, val = 3)
+c([4, 3, 1, 3]; op = >, val = 0)
+```
+"""
 function xcsp_circuit(; list, size = nothing)
     return if isnothing(size)
         concept_circuit(list)
@@ -6,8 +36,6 @@ function xcsp_circuit(; list, size = nothing)
     end
 end
 
-const description_circuit = "Global constraint ensuring that the values of `x` form a circuit. If the indices of the variables are not `1:length(x)`, the indices can be indicated as the `param` collection"
-
 # circuit (full circuit)
 @usual function concept_circuit(x; op = ≥, val = length(x))
     V = Set(1:length(x))