big update of docstrings

Author: ocots

Project.toml

@@ -1,7 +1,7 @@
 name = "CTModels"
 uuid = "34c4fa32-2049-4079-8329-de33c2a22e2d"
 authors = ["Olivier Cots <olivier.cots@toulouse-inp.fr>"]
-version = "0.5.2"
+version = "0.5.3"
 
 [deps]
 CTBase = "54762871-cc72-4466-b8e8-f6c8b58076cd"

ext/CTModelsJLD.jl

@@ -21,6 +21,7 @@ allowing it to be reloaded later.
 
 # Example
 ```julia-repl
+julia> using JLD2
 julia> export_ocp_solution(JLD2Tag(), sol; filename="mysolution")
 # → creates "mysolution.jld2"
 ```
@@ -51,6 +52,7 @@ This function loads a previously saved `CTModels.Solution` from disk.
 
 # Example
 ```julia-repl
+julia> using JLD2
 julia> sol = import_ocp_solution(JLD2Tag(), model; filename="mysolution")
 ```
 """

ext/CTModelsJSON.jl

@@ -25,6 +25,7 @@ The exported JSON includes the time grid, state, control, costate, objective, so
 
 # Example
 ```julia-repl
+julia> using JSON3
 julia> export_ocp_solution(JSON3Tag(), sol; filename="mysolution")
 # → creates "mysolution.json"
 ```
@@ -91,6 +92,7 @@ Handles both vector and matrix encodings of signals. If dual fields are missing
 
 # Example
 ```julia-repl
+julia> using JSON3
 julia> sol = import_ocp_solution(JSON3Tag(), model; filename="mysolution")
 ```
 """

ext/plot.jl

@@ -464,13 +464,11 @@ constraints, and duals based on the provided `layout` and `description`.
 Includes options such as:
 - `layout`, `control`, `time`
 - `state_style`, `control_style`, `costate_style`, etc.
-- `solution_label`: Label to annotate the plotted solution.
 """
 function __plot!(
     p::Plots.Plot,
     sol::CTModels.Solution,
     description::Symbol...;
-    solution_label::String,
     model::Union{CTModels.Model,Nothing},
     time::Symbol,
     control::Symbol,
@@ -511,11 +509,6 @@ function __plot!(
         path_bounds_style=path_bounds_style,
     )
 
-    # add an empty space to the label if the label is not empty
-    if solution_label != ""
-        @warn "Deprecated: `solution_label` keyword argument is replaced by `label`."
-    end
-
     #
     n = CTModels.state_dimension(sol)
     m = CTModels.control_dimension(sol)
@@ -1018,7 +1011,6 @@ Use this to obtain a standalone plot.
 function __plot(
     sol::CTModels.Solution,
     description::Symbol...;
-    solution_label::String,
     model::Union{CTModels.Model,Nothing},
     time::Symbol,
     control::Symbol,
@@ -1068,7 +1060,6 @@ function __plot(
         layout=layout,
         control=control,
         time=time,
-        solution_label=solution_label,
         state_style=state_style,
         control_style=control_style,
         costate_style=costate_style,
@@ -1088,9 +1079,9 @@ end
 """
 $(TYPEDSIGNATURES)
 
-Update an existing plot `p` with the optimal control `Solution`.
+Modify Plot `p` with the optimal control solution `sol`.
 
-See `__plot!` for full behavior and keyword arguments.
+See [`plot`](@ref plot(::CTModels.Solution)) for full behavior and keyword arguments.
 """
 function Plots.plot!(
     p::Plots.Plot,
@@ -1099,7 +1090,6 @@ function Plots.plot!(
     layout::Symbol=__plot_layout(),
     control::Symbol=__control_layout(),
     time::Symbol=__time_normalization(),
-    solution_label::String=__plot_label_suffix(),
     state_style::Union{NamedTuple,Symbol}=__plot_style(),
     state_bounds_style::Union{NamedTuple,Symbol}=__plot_style(),
     control_style::Union{NamedTuple,Symbol}=__plot_style(),
@@ -1158,7 +1148,6 @@ function Plots.plot!(
         layout=layout,
         control=control,
         time=time,
-        solution_label=solution_label,
         state_style=state_style,
         control_style=control_style,
         costate_style=costate_style,
@@ -1176,9 +1165,53 @@ end
 """
 $(TYPEDSIGNATURES)
 
+Modify Plot `current()` with the optimal control solution `sol`.
+
+See [`plot`](@ref plot(::CTModels.Solution)) for full behavior and keyword arguments.
+"""
+function Plots.plot!(
+    sol::CTModels.Solution,
+    description::Symbol...;
+    layout::Symbol=__plot_layout(),
+    control::Symbol=__control_layout(),
+    time::Symbol=__time_normalization(),
+    state_style::Union{NamedTuple,Symbol}=__plot_style(),
+    state_bounds_style::Union{NamedTuple,Symbol}=__plot_style(),
+    control_style::Union{NamedTuple,Symbol}=__plot_style(),
+    control_bounds_style::Union{NamedTuple,Symbol}=__plot_style(),
+    costate_style::Union{NamedTuple,Symbol}=__plot_style(),
+    time_style::Union{NamedTuple,Symbol}=__plot_style(),
+    path_style::Union{NamedTuple,Symbol}=__plot_style(),
+    path_bounds_style::Union{NamedTuple,Symbol}=__plot_style(),
+    dual_style::Union{NamedTuple,Symbol}=__plot_style(),
+    kwargs...,
+)
+    return Plots.plot!(
+        Plots.current(),
+        sol,
+        description...;
+        layout,
+        control,
+        time,
+        state_style,
+        state_bounds_style,
+        control_style,
+        control_bounds_style,
+        costate_style,
+        time_style,
+        path_style,
+        path_bounds_style,
+        dual_style,
+        kwargs...,
+    )
+end
+
+"""
+$(TYPEDSIGNATURES)
+
 Plot the components of an optimal control solution.
 
-This is the main user-facing function to visualize the solution of an optimal control problem
+This is the main user-facing function to visualise the solution of an optimal control problem
 solved with the control-toolbox ecosystem.
 
 It generates a set of subplots showing the evolution of the state, control, costate,
@@ -1211,13 +1244,11 @@ If no symbols are provided, a default set is used based on the problem and style
   - `:default`: Real time scale.
   - `:normalize` or `:normalise`: Normalised to the interval [0, 1].
 
-- `solution_label::String = ""`: Label to annotate this solution in the legend. (Deprecated: use `label` instead) 
-
 ## Style Options (Optional)
 
 All style-related keyword arguments can be either a `NamedTuple` of plotting attributes or the `Symbol` `:none` referring to not plot the associated element. These allow you to customise color, line style, markers, etc.
 
-- `time_style`: Style for vertical lines at initial and final time.
+- `time_style`: Style for vertical lines at initial and final times.
 - `state_style`: Style for state components.
 - `costate_style`: Style for costate components.
 - `control_style`: Style for control components.
@@ -1234,7 +1265,7 @@ Use these options to customise bounds on the plots if applicable and defined in
 
 # Returns
 
-- A `Plots.Plot` object, which can be displayed, saved, or further customized.
+- A `Plots.Plot` object, which can be displayed, saved, or further customised.
 
 # Example
 
@@ -1247,7 +1278,7 @@ julia> plot(sol, :state, :control)
 
 # customise layout and styles, no costate
 julia> plot(sol;
-       layout = :split,
+       layout = :group,
        control = :all,
        state_style = (color=:blue, linestyle=:solid),
        control_style = (color=:red, linestyle=:dash),
@@ -1260,7 +1291,6 @@ function Plots.plot(
     layout::Symbol=__plot_layout(),
     control::Symbol=__control_layout(),
     time::Symbol=__time_normalization(),
-    solution_label::String=__plot_label_suffix(),
     state_style::Union{NamedTuple,Symbol}=__plot_style(),
     state_bounds_style::Union{NamedTuple,Symbol}=__plot_style(),
     control_style::Union{NamedTuple,Symbol}=__plot_style(),
@@ -1290,7 +1320,6 @@ function Plots.plot(
         layout=layout,
         control=control,
         time=time,
-        solution_label=solution_label,
         state_style=state_style,
         control_style=control_style,
         costate_style=costate_style,

src/CTModels.jl

@@ -130,53 +130,43 @@ JSON tag for export/import functions.
 """
 struct JSON3Tag <: AbstractTag end
 
-# to be extended
-"""
-$(TYPEDSIGNATURES)
+# -----------------------------
+# to be extended: no docstrings
+function RecipesBase.plot(sol::AbstractSolution, description::Symbol...; kwargs...)
+    throw(CTBase.ExtensionError(:Plots))
+end
 
-Export a solution in JLD format.
-"""
 function export_ocp_solution(::JLD2Tag, ::AbstractSolution; filename::String)
     throw(CTBase.ExtensionError(:JLD2))
 end
 
-"""
-$(TYPEDSIGNATURES)
-
-Import a solution from a JLD file.
-"""
 function import_ocp_solution(::JLD2Tag, ::AbstractModel; filename::String)
     throw(CTBase.ExtensionError(:JLD2))
 end
 
-"""
-$(TYPEDSIGNATURES)
-
-Export a solution in JSON format.
-"""
 function export_ocp_solution(::JSON3Tag, ::AbstractSolution; filename::String)
     throw(CTBase.ExtensionError(:JSON3))
 end
 
-"""
-$(TYPEDSIGNATURES)
-
-Import a solution from a JLD file.
-"""
 function import_ocp_solution(::JSON3Tag, ::AbstractModel; filename::String)
     throw(CTBase.ExtensionError(:JSON3))
 end
 
 """
 $(TYPEDSIGNATURES)
 
-Export a solution in JLD or JSON formats.
+Export a solution in JLD or JSON formats. Redirect to one of the methods:
+
+- [`export_ocp_solution(JLD2Tag(), sol, filename=filename)`](@ref export_ocp_solution(::CTModels.JLD2Tag, ::CTModels.Solution))
+- [`export_ocp_solution(JSON3Tag(), sol, filename=filename)`](@ref export_ocp_solution(::CTModels.JSON3Tag, ::CTModels.Solution))
 
 # Examples
 
 ```julia-repl
-julia> CTModels.export_ocp_solution(sol; filename="solution", format=:JSON)
-julia> CTModels.export_ocp_solution(sol; filename="solution", format=:JLD)
+julia> using JSON3
+julia> export_ocp_solution(sol; filename="solution", format=:JSON)
+julia> using JLD2
+julia> export_ocp_solution(sol; filename="solution", format=:JLD)  # JLD is the default
 ```
 """
 function export_ocp_solution(
@@ -200,13 +190,18 @@ end
 """
 $(TYPEDSIGNATURES)
 
-Import a solution from a JLD or JSON file.
+Import a solution from a JLD or JSON file. Redirect to one of the methods:
+
+- [`import_ocp_solution(JLD2Tag(), ocp, filename=filename)`](@ref import_ocp_solution(::CTModels.JLD2Tag, ::CTModels.Model))
+- [`import_ocp_solution(JSON3Tag(), ocp, filename=filename)`](@ref import_ocp_solution(::CTModels.JSON3Tag, ::CTModels.Model))
 
 # Examples
 
 ```julia-repl
-julia> sol = CTModels.import_ocp_solution(ocp; filename="solution", format=:JSON)
-julia> sol = CTModels.import_ocp_solution(ocp; filename="solution", format=:JLD)
+julia> using JSON3
+julia> sol = import_ocp_solution(ocp; filename="solution", format=:JSON)
+julia> using JLD2
+julia> sol = import_ocp_solution(ocp; filename="solution", format=:JLD)  # JLD is the default
 ```
 """
 function import_ocp_solution(
@@ -227,38 +222,6 @@ function import_ocp_solution(
     end
 end
 
-# to be extended
-"""
-$(TYPEDSIGNATURES)
-
-Plot a solution from an optimal control problem.
-
-This function dispatches on a solution type that inherits from `AbstractSolution`. It is intended to visualize various components of the solution (such as state trajectories, controls, costates, or any other variables defined in the model).
-
-!!! note
-    This function requires the `Plots.jl` package to be available. If it is not loaded, a `CTBase.ExtensionError(:Plots)` is thrown.
-
-# Arguments
-- `sol::AbstractSolution`: A solution object returned by solving a control problem.
-- `description::Symbol...`: Optional symbols specifying what to plot (e.g., `:state`, `:control`, `:costate`, etc.). If empty, a default set of components is plotted.
-- `kwargs...`: Additional keyword arguments passed to the underlying plotting routines (e.g., `xlabel`, `ylabel`, `legend`, etc.).
-
-# Returns
-- A plot object (if `Plots.jl` is available) visualizing the selected components of the solution.
-
-# Example
-```julia-repl
-julia> using Plots
-julia> plot(sol, :state, :control, xlabel = "Time", layout = (2,1))
-```
-
-# Throws
-- `CTBase.ExtensionError` if the `Plots` package is not available or not loaded.
-"""
-function RecipesBase.plot(sol::AbstractSolution, description::Symbol...; kwargs...)
-    throw(CTBase.ExtensionError(:Plots))
-end
-
 #
 include("init.jl")
 include("dual_model.jl")

src/constraints.jl

@@ -562,9 +562,8 @@ end
 $(TYPEDSIGNATURES)
 
 Get a labelled constraint from the model. Returns a tuple of the form
-`(type, f, lb, ub)` where `type` is the type of the constraint, `f` is the function
-of the constraint, `lb` is the lower bound of the constraint and `ub` is the upper
-bound of the constraint. 
+`(type, f, lb, ub)` where `type` is the type of the constraint, `f` is the function, 
+`lb` is the lower bound and `ub` is the upper bound. 
 
 The function returns an exception if the label is not found in the model.
 
@@ -576,14 +575,6 @@ The function returns an exception if the label is not found in the model.
 ## Returns
 
 - `Tuple`: A tuple containing the type, function, lower bound, and upper bound of the constraint.
-
-## Example
-
-```julia-repl
-julia> # Example of getting a labelled constraint from the model
-julia> model = Model(...)
-julia> constraint_info = constraint(model, :my_constraint)
-```
 """
 function constraint(model::Model, label::Symbol)::Tuple # not type stable
 

src/dual_model.jl

@@ -9,8 +9,7 @@ $(TYPEDSIGNATURES)
 Return the dual variable associated with a constraint identified by its `label`.
 
 Searches through all constraint types (path, boundary, state, control, and variable constraints)
-defined in the model and returns the corresponding dual value(s) from the solution. If the label
-is found multiple times, a vector of values is returned.
+defined in the model and returns the corresponding dual value from the solution.
 
 # Arguments
 - `sol::Solution`: Solution object containing dual variables.
@@ -20,12 +19,6 @@ is found multiple times, a vector of values is returned.
 # Returns
 A function of time `t` for time-dependent constraints, or a scalar/vector for time-invariant duals.
 If the label is not found, throws an `IncorrectArgument` exception.
-
-# Examples
-```julia-repl
-julia> dual_fun = dual(sol, model, :velocity_limit)
-julia> dual_value_at_t1 = dual_fun(1.0)
-```
 """
 function dual(sol::Solution, model::Model, label::Symbol)