Merge pull request #364 from control-toolbox/348-doc-improve-info-on-…

…internal-function-clean

up doc

.github/workflows/Formatter.yml

@@ -17,7 +17,7 @@ jobs:
  - name: Install JuliaFormatter and format
  run: |
  julia -e 'import Pkg; Pkg.add("JuliaFormatter")'
- julia -e 'using JuliaFormatter; format(".")'
+ julia -e 'using JuliaFormatter; format(".", BlueStyle())'
  # https://github.com/marketplace/actions/create-pull-request
  # https://github.com/peter-evans/create-pull-request#reference-example
  - name: Create Pull Request

docs/Project.toml

@@ -16,6 +16,7 @@ MINPACK = "4854310b-de5a-5eb6-a2a5-c1dee2bd17f9"
 MadNLP = "2621e9c9-9eb4-46b1-8089-e8c72242dfb6"
 NLPModelsIpopt = "f4238b75-b362-5c4c-b852-0801c9a21d71"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
+OptimalControl = "5f98b655-cc9a-415a-b60e-744165666948"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 Percival = "01435c0c-c90d-11e9-3788-63660f8fbccc"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"

docs/src/api-ctbase.md

@@ -8,7 +8,7 @@ The [CTBase.jl](control-toolbox.org/CTBase.jl/) package is part of the [control-
 
 ```mermaid
 flowchart TD
-O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/'>OptimalControl</a>) --> B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
+O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>) --> B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
 O --> D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
 O --> F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
 F --> B

docs/src/api-ctdirect.md

@@ -8,7 +8,7 @@ The [CTDirect.jl](control-toolbox.org/CTDirect.jl) package is part of the [contr
 
 ```mermaid
 flowchart TD
-O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/'>OptimalControl</a>) --> B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
+O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>) --> B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
 O --> D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
 O --> F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
 F --> B

docs/src/api-ctflows.md

@@ -8,7 +8,7 @@ The [CTFlows.jl](control-toolbox.org/CTFlows.jl) package is part of the [control
 
 ```mermaid
 flowchart TD
-O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/'>OptimalControl</a>) --> B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
+O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>) --> B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
 O --> D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
 O --> F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
 F --> B

docs/src/api-optimalcontrol.md

@@ -8,7 +8,7 @@ The [OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) package i
 
 ```mermaid
 flowchart TD
-O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/'>OptimalControl</a>) --> B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
+O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>) --> B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
 O --> D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
 O --> F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
 F --> B

src/solve.jl

@@ -1,7 +1,7 @@
 """
 $(TYPEDSIGNATURES)
 
-Return the list of available methods to solve the optimal control problem.
+Return the list of available methods that can be used to solve the optimal control problem.
 """
 function available_methods()
  # by order of preference: from top to bottom
@@ -15,8 +15,13 @@ end
 """
 $(TYPEDSIGNATURES)
 
-Remove from the description, the Symbol that are specific to [OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) and so must not 
-be passed.
+When calling the function `solve`, the user can provide a description of the method to use to solve the optimal control problem.
+The description can be a partial description or a full description.
+The function `solve` will find the best match from the available methods, thanks to the function `getFullDescription`.
+Then, the description is cleaned by the function `clean` to remove the Symbols that are specific to 
+[OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) and so must not be passed to the solver.
+For instance, the Symbol `:direct` is specific to [OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) and must be removed.
+It must not be passed to the CTDirect.jl solver.
 """
 function clean(d::Description)
  return remove(d, (:direct,))
@@ -26,37 +31,67 @@ end
 $(TYPEDSIGNATURES)
 
 Solve the the optimal control problem `ocp` by the method given by the (optional) description.
+The available methods are given by `available_methods()`.
+The higher in the list, the higher is the priority.
+The keyword arguments are specific to the chosen method and represent the options of the solver.
 
-# The (optional) description
+!!! note
+ See the [tutorial on solving optimal control problems](@ref tutorial-solve) for more information.
 
-You can pass a partial description.
-If you give a partial description, then, if several complete descriptions contains the partial one, 
-then, the method with the highest priority is chosen. The higher in the list, 
-the higher is the priority. To get the list of available methods, call `available_methods()`.
+# Arguments
 
-Keyword arguments: you can pass any other option by a pair `keyword=value` according to the chosen method.
+- `ocp::OptimalControlModel`: the optimal control problem to solve.
+- `description::Symbol...`: the description of the method to use to solve the problem.
+- `kwargs...`: the options of the solver.
 
 # Examples
 
-```julia-repl
+The simplest way to solve the optimal control problem is to call the function without any argument.
+
+```julia-rep
 julia> sol = solve(ocp)
+```
+
+The method can be specified by passing the description as a Symbol. You can provide a partial description, the function will 
+find the best match.
+
+```julia-rep
 julia> sol = solve(ocp, :direct)
-julia> sol = solve(ocp, :direct, :ipopt)
+```
+
+The method can be specified by passing the full description as a list of Symbols.
+
+```julia-repl
+julia> sol = solve(ocp, :direct, :adnlp, :ipopt)
+```
+
+The keyword arguments are specific to the chosen method and represent the options of the solver.
+For example, the keyword `display` is used to display the information of the solver.
+The default value is `true`.
+
+```julia-rep
 julia> sol = solve(ocp, :direct, :ipopt, display=false)
-julia> sol = solve(ocp, :direct, :ipopt, display=false, init=sol)
-julia> sol = solve(ocp, init=(state=[-0.5, 0.2],))
+```
+
+The initial guess can be provided by the keyword `init`.
+You can provide the initial guess for the state, control, and variable.
+
+```julia-rep
 julia> sol = solve(ocp, init=(state=[-0.5, 0.2], control=0.5))
-julia> sol = solve(ocp, init=(state=[-0.5, 0.2], control=0.5, variable=[1, 2]))
-julia> sol = solve(ocp, init=(state=[-0.5, 0.2], control=t->6-12*t))
-julia> sol = solve(ocp, init=(state=t->[-1+t, t*(t-1)], control=0.5))
-julia> sol = solve(ocp, init=(state=t->[-1+t, t*(t-1)], control=t->6-12*t))
 ```
+
+!!! tip 
+ For more information on how to provide the initial guess, see the [tutorial on the initial guess](@ref tutorial-init).
+
 """
-function CommonSolve.solve(ocp::OptimalControlModel, description::Symbol...; kwargs...)
+function CommonSolve.solve(ocp::OptimalControlModel, description::Symbol...; kwargs...)::OptimalControlSolution
 
  # get the full description
  method = getFullDescription(description, available_methods())
 
  # solve the problem
- :direct ∈ method && return CTDirect.direct_solve(ocp, clean(description)...; kwargs...)
+ if :direct ∈ method 
+ return CTDirect.direct_solve(ocp, clean(description)...; kwargs...)
+ end
+
 end