Merge pull request #123 from control-toolbox/122-doc-update-docstrings

Update docstrings

Author: ocots

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 
 [compat]
 Documenter = "1"

docs/make.jl

@@ -1,5 +1,13 @@
 using Documenter
 using CTModels
+using Plots
+
+# to add docstrings from external packages
+Modules = [Plots]
+for Module in Modules
+    isnothing(DocMeta.getdocmeta(Module, :DocTestSetup)) &&
+        DocMeta.setdocmeta!(Module, :DocTestSetup, :(using $Module); recursive=true)
+end
 
 repo_url = "github.com/control-toolbox/CTModels.jl"
 

docs/src/dev.md

@@ -28,3 +28,6 @@ Modules = [CTModels]
 Order   = [:constant, :type, :function, :macro]
 ```
 
+```@docs
+plot(::CTModels.Solution, ::Symbol...)
+```

ext/CTModelsJLD.jl

@@ -6,8 +6,24 @@ using JLD2
 
 """
 $(TYPEDSIGNATURES)
-  
-Export OCP solution in JLD format
+
+Export an optimal control solution to a `.jld2` file using the JLD2 format.
+
+This function serializes and saves a `CTModels.Solution` object to disk,
+allowing it to be reloaded later.
+
+# Arguments
+- `::CTModels.JLD2Tag`: A tag used to dispatch the export method for JLD2.
+- `sol::CTModels.Solution`: The optimal control solution to be saved.
+
+# Keyword Arguments
+- `filename::String = "solution"`: Base name of the file. The `.jld2` extension is automatically appended.
+
+# Example
+```julia-repl
+julia> export_ocp_solution(JLD2Tag(), sol; filename="mysolution")
+# → creates "mysolution.jld2"
+```
 """
 function CTModels.export_ocp_solution(
     ::CTModels.JLD2Tag, sol::CTModels.Solution; filename::String="solution"
@@ -18,8 +34,25 @@ end
 
 """
 $(TYPEDSIGNATURES)
-  
-Import OCP solution in JLD format
+
+Import an optimal control solution from a `.jld2` file.
+
+This function loads a previously saved `CTModels.Solution` from disk.
+
+# Arguments
+- `::CTModels.JLD2Tag`: A tag used to dispatch the import method for JLD2.
+- `ocp::CTModels.Model`: The associated model (used for dispatch consistency; not used internally).
+
+# Keyword Arguments
+- `filename::String = "solution"`: Base name of the file. The `.jld2` extension is automatically appended.
+
+# Returns
+- `CTModels.Solution`: The loaded solution object.
+
+# Example
+```julia-repl
+julia> sol = import_ocp_solution(JLD2Tag(), model; filename="mysolution")
+```
 """
 function CTModels.import_ocp_solution(
     ::CTModels.JLD2Tag, ocp::CTModels.Model; filename::String="solution"

ext/CTModelsJSON.jl

@@ -7,8 +7,27 @@ using JSON3
 
 """
 $(TYPEDSIGNATURES)
-  
-Export OCP solution in JSON format
+
+Export an optimal control solution to a `.json` file using the JSON3 format.
+
+This function serializes a `CTModels.Solution` into a structured JSON dictionary,
+including all primal and dual information, which can be read by external tools.
+
+# Arguments
+- `::CTModels.JSON3Tag`: A tag used to dispatch the export method for JSON3.
+- `sol::CTModels.Solution`: The solution to be saved.
+
+# Keyword Arguments
+- `filename::String = "solution"`: Base filename. The `.json` extension is automatically appended.
+
+# Notes
+The exported JSON includes the time grid, state, control, costate, objective, solver info, and all constraint duals (if available).
+
+# Example
+```julia-repl
+julia> export_ocp_solution(JSON3Tag(), sol; filename="mysolution")
+# → creates "mysolution.json"
+```
 """
 function CTModels.export_ocp_solution(
     ::CTModels.JSON3Tag, sol::CTModels.Solution; filename::String="solution"
@@ -51,8 +70,29 @@ end
 
 """
 $(TYPEDSIGNATURES)
-  
-Import OCP solution in JSON format
+
+Import an optimal control solution from a `.json` file exported with `export_ocp_solution`.
+
+This function reads the JSON contents and reconstructs a `CTModels.Solution` object,
+including the discretized primal and dual trajectories.
+
+# Arguments
+- `::CTModels.JSON3Tag`: A tag used to dispatch the import method for JSON3.
+- `ocp::CTModels.Model`: The model associated with the optimal control problem. Used to rebuild the full solution.
+
+# Keyword Arguments
+- `filename::String = "solution"`: Base filename. The `.json` extension is automatically appended.
+
+# Returns
+- `CTModels.Solution`: A reconstructed solution instance.
+
+# Notes
+Handles both vector and matrix encodings of signals. If dual fields are missing or `null`, the corresponding attributes are set to `nothing`.
+
+# Example
+```julia-repl
+julia> sol = import_ocp_solution(JSON3Tag(), model; filename="mysolution")
+```
 """
 function CTModels.import_ocp_solution(
     ::CTModels.JSON3Tag, ocp::CTModels.Model; filename::String="solution"

ext/default.jl

@@ -1,30 +1,59 @@
 """
 $(TYPEDSIGNATURES)
 
-Used to set the default value of the layout of the plots.
-Either :split or :group.
+Default layout for the full plot.
+
+Returns `:split`, which arranges each component (e.g. state, control) in separate subplots.
+
+Possible values:
+- `:split`: One subplot per component (default).
+- `:group`: Combine components into shared subplots.
+
+Used as the default for `layout` in `plot(sol; layout=...)`.
 """
 __plot_layout() = :split
 
 """
 $(TYPEDSIGNATURES)
 
-Used to set the default value of the layout of the control plots.
-Either :components or :norm or :all.
+Default layout for control input visualization.
+
+Returns `:components`, which plots each control component individually.
+
+Possible values:
+- `:components`: One plot per control component (default).
+- `:norm`: Single plot showing the control norm ‖u(t)‖.
+- `:all`: Show both components and norm.
+
+Used as the default for `control` in `plot(sol; control=...)`.
 """
 __control_layout() = :components
 
 """
 $(TYPEDSIGNATURES)
 
-Used to set the default value of the time grid normalization.
-Either :default or :normalize or :normalise.
+Default time axis normalization.
+
+Returns `:default`, which plots against real time.
+
+Possible values:
+- `:default`: Plot time in original units (default).
+- `:normalize`: Normalize time to [0, 1].
+- `:normalise`: Same as `:normalize`, British spelling.
+
+Used as the default for `time` in `plot(sol; time=...)`.
 """
 __time_normalization() = :default
 
 """
 $(TYPEDSIGNATURES)
 
+Return the default list of description symbols to be plotted if the user does not specify any.
+
+Includes aliases for backward compatibility.
+
+Returns a tuple of symbols, such as:
+- `:state`, `:costate`, `:control`, `:path`, `:dual`, ...
 """
 function __description()
     (
@@ -46,7 +75,20 @@ end
 """
 $(TYPEDSIGNATURES)
 
-Used to set the default value of the plot size.
+Compute a default size `(width, height)` for the plot figure.
+
+This depends on the number of subplots, which is inferred from:
+- The layout (`:group` or `:split`)
+- The presence of state, control, costate, path constraint, or dual variable plots
+- The number of state and control variables
+- The control layout choice (`:components`, `:norm`, `:all`)
+
+Used internally in the `plot` function to automatically size the output plot.
+
+# Example
+```julia-repl
+julia> size = __size_plot(sol, model, :components, :split; ...)
+```
 """
 function __size_plot(
     sol::CTModels.Solution,
@@ -124,13 +166,21 @@ end
 """
 $(TYPEDSIGNATURES)
 
-Default style for the plot. Must be an empty tuple.
+Default plot style.
+
+Returns an empty `NamedTuple()`, which means no style override is applied.
+
+Used when no user-defined style is passed for plotting states, controls, etc.
 """
 __plot_style() = NamedTuple()
 
 """
 $(TYPEDSIGNATURES)
 
-Default suffix label for the plot. Must be an empty string.
+Default suffix used for the solution label in plots.
+
+Returns an empty string `""`.
+
+This label can be used to distinguish multiple solutions in comparative plots.
 """
 __plot_label_suffix() = ""