Merge pull request #74 from control-toolbox/doc

add docstrings

Author: ocots

docs/make.jl

@@ -16,7 +16,9 @@ makedocs(;
             asset("https://control-toolbox.org/assets/js/documentation.js"),
         ],
     ),
-    pages=["Introduction" => "index.md", "Developers" => "dev.md"],
+    pages=[
+        "Introduction" => "index.md", 
+        "Developers" => "dev.md"],
     checkdocs=:none,
 )
 

docs/src/dev.md

@@ -8,10 +8,9 @@ CurrentModule =  CTModels
 ## CTModels 
 
 ```@autodocs
+Pages   = ["CTModels.jl"]
 Modules = [CTModels]
 Order   = [:module]
-Pages   = ["CTModels.jl"]
-Private = false
 ```
 
 ## Index
@@ -27,6 +26,5 @@ Order   = [:constant, :type, :function, :macro]
 ```@autodocs
 Modules = [CTModels]
 Order   = [:constant, :type, :function, :macro]
-Public  = false
 ```
 

ext/CTModelsJLD.jl

@@ -3,7 +3,6 @@ module CTModelsJLD
 using CTBase
 using CTModels
 using DocStringExtensions
-
 using JLD2
 
 """
@@ -21,7 +20,7 @@ end
 """
 $(TYPEDSIGNATURES)
   
-Read OCP solution in JLD format
+Import OCP solution in JLD format
 """
 function CTModels.import_ocp_solution(
     ::CTModels.JLD2Tag, ocp::CTModels.Model; filename_prefix="solution"

ext/CTModelsJSON.jl

@@ -55,7 +55,7 @@ end
 """
 $(TYPEDSIGNATURES)
   
-Read OCP solution in JSON format
+Import OCP solution in JSON format
 """
 function CTModels.import_ocp_solution(
     ::CTModels.JSON3Tag, ocp::CTModels.Model; filename_prefix="solution"

src/CTModels.jl

@@ -4,6 +4,10 @@
 Lists all the imported modules and packages:
 
 $(IMPORTS)
+
+List of all the exported names:
+
+$(EXPORTS)
 """
 module CTModels
 
@@ -16,33 +20,152 @@ using MLStyle
 using Parameters # @with_kw: to have default values in struct
 using MacroTools: striplines
 using PrettyTables # To print a table
-import RecipesBase: plot, plot!, RecipesBase
+using RecipesBase: plot, plot!, RecipesBase
 
 # aliases
+
+"""
+Type alias for a dimension. This is used to define the dimension of the state space, 
+the costate space, the control space, etc.
+
+```@example
+julia> const Dimension = Integer
+```
+"""
 const Dimension = Int
+
+"""
+Type alias for a real number.
+
+```@example
+julia> const ctNumber = Real
+```
+"""
 const ctNumber = Real
+
+"""
+Type alias for a time.
+
+```@example
+julia> const Time = ctNumber
+```
+
+See also: [`ctNumber`](@ref), [`Times`](@ref), [`TimesDisc`](@ref).
+"""
 const Time = ctNumber
+
+"""
+Type alias for a vector of real numbers.
+
+```@example
+julia> const ctVector = AbstractVector{<:ctNumber}
+```
+
+See also: [`ctNumber`](@ref).
+"""
 const ctVector = AbstractVector{<:ctNumber}
+
+"""
+Type alias for a vector of times.
+
+```@example
+julia> const Times = AbstractVector{<:Time}
+```
+
+See also: [`Time`](@ref), [`TimesDisc`](@ref).
+"""
+const Times = AbstractVector{<:Time}
+
+"""
+Type alias for a grid of times. This is used to define a discretization of time interval given to solvers.
+
+```@example
+julia> const TimesDisc = Union{Times, StepRangeLen}
+```
+
+See also: [`Time`](@ref), [`Times`](@ref).
+"""
+const TimesDisc = Union{Times,StepRangeLen}
+
+"""
+Type alias for a dictionnary of constraints. This is used to store constraints before building the model.
+
+```@example
+julia> const TimesDisc = Union{Times, StepRangeLen}
+```
+
+See also: [`ConstraintsModel`](@ref), [`PreModel`](@ref) and [`Model`](@ref).
+"""
 const ConstraintsDictType = Dict{
     Symbol,Tuple{Symbol,Union{Function,OrdinalRange{<:Int}},ctVector,ctVector}
 }
-const Times = AbstractVector{<:Time}
-const TimesDisc = Union{Times,StepRangeLen}
 
 #
 include("default.jl")
 
 # export / import
+"""
+$(TYPEDEF)
+
+Abstract type for export/import functions, used to choose between JSON or JLD extensions.
+"""
 abstract type AbstractTag end
+
+"""
+$(TYPEDEF)
+
+JLD tag for export/import functions.
+"""
 struct JLD2Tag <: AbstractTag end
+
+"""
+$(TYPEDEF)
+
+JSON tag for export/import functions.
+"""
 struct JSON3Tag <: AbstractTag end
 
 # to be extended
+"""
+$(TYPEDSIGNATURES)
+
+Export a solution in JLD format.
+"""
 export_ocp_solution(::JLD2Tag, args...; kwargs...) = throw(CTBase.ExtensionError(:JLD2))
+
+"""
+$(TYPEDSIGNATURES)
+
+Import a solution from a JLD file.
+"""
 import_ocp_solution(::JLD2Tag, args...; kwargs...) = throw(CTBase.ExtensionError(:JLD2))
+
+"""
+$(TYPEDSIGNATURES)
+
+Export a solution in JSON format.
+"""
 export_ocp_solution(::JSON3Tag, args...; kwargs...) = throw(CTBase.ExtensionError(:JSON3))
+
+"""
+$(TYPEDSIGNATURES)
+
+Import a solution from a JLD file.
+"""
 import_ocp_solution(::JSON3Tag, args...; kwargs...) = throw(CTBase.ExtensionError(:JSON3))
 
+"""
+$(TYPEDSIGNATURES)
+
+Export a solution in JLD or JSON formats.
+
+# Examples
+
+```julia-repl
+julia> CTModels.export_ocp_solution(sol; filename_prefix="solution", format=:JSON)
+julia> CTModels.export_ocp_solution(sol; filename_prefix="solution", format=:JLD)
+```
+"""
 function export_ocp_solution(args...; format=__format(), kwargs...)
     if format == :JLD
         return export_ocp_solution(JLD2Tag(), args...; kwargs...)
@@ -57,6 +180,18 @@ function export_ocp_solution(args...; format=__format(), kwargs...)
     end
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+Import a solution from a JLD or JSON file.
+
+# Examples
+
+```julia-repl
+julia> sol = CTModels.import_ocp_solution(ocp; filename_prefix="solution", format=:JSON)
+julia> sol = CTModels.import_ocp_solution(ocp; filename_prefix="solution", format=:JLD)
+```
+"""
 function import_ocp_solution(args...; format=__format(), kwargs...)
     if format == :JLD
         return import_ocp_solution(JLD2Tag(), args...; kwargs...)
@@ -76,9 +211,20 @@ include("utils.jl")
 include("types.jl")
 
 # to be extended
+"""
+$(TYPEDSIGNATURES)
+
+Plot a solution.
+"""
 function RecipesBase.plot(sol::AbstractSolution; kwargs...)
     throw(CTBase.ExtensionError(:Plots))
 end
+
+"""
+$(TYPEDSIGNATURES)
+
+Plot a solution on an existing plot.
+"""
 function RecipesBase.plot!(p::RecipesBase.AbstractPlot, sol::AbstractSolution; kwargs...)
     throw(CTBase.ExtensionError(:Plots))
 end

src/dual_model.jl

@@ -15,6 +15,10 @@
 # variable_constraints_lb_dual::VC_LB_Dual
 # variable_constraints_ub_dual::VC_UB_Dual
 
+"""
+$(TYPEDSIGNATURES)
+
+"""
 function path_constraints(
     model::DualModel{
         PC,
@@ -32,6 +36,10 @@ function path_constraints(
     return model.path_constraints
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+"""
 function path_constraints_dual(
     model::DualModel{
         <:Union{Function,Nothing},
@@ -49,6 +57,10 @@ function path_constraints_dual(
     return model.path_constraints_dual
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+"""
 function boundary_constraints(
     model::DualModel{
         <:Union{Function,Nothing},
@@ -66,6 +78,10 @@ function boundary_constraints(
     return model.boundary_constraints
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+"""
 function boundary_constraints_dual(
     model::DualModel{
         <:Union{Function,Nothing},
@@ -83,6 +99,10 @@ function boundary_constraints_dual(
     return model.boundary_constraints_dual
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+"""
 function state_constraints_lb_dual(
     model::DualModel{
         <:Union{Function,Nothing},
@@ -100,6 +120,10 @@ function state_constraints_lb_dual(
     return model.state_constraints_lb_dual
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+"""
 function state_constraints_ub_dual(
     model::DualModel{
         <:Union{Function,Nothing},
@@ -117,6 +141,10 @@ function state_constraints_ub_dual(
     return model.state_constraints_ub_dual
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+"""
 function control_constraints_lb_dual(
     model::DualModel{
         <:Union{Function,Nothing},
@@ -134,6 +162,10 @@ function control_constraints_lb_dual(
     return model.control_constraints_lb_dual
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+"""
 function control_constraints_ub_dual(
     model::DualModel{
         <:Union{Function,Nothing},
@@ -151,6 +183,10 @@ function control_constraints_ub_dual(
     return model.control_constraints_ub_dual
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+"""
 function variable_constraints_lb_dual(
     model::DualModel{
         <:Union{Function,Nothing},
@@ -168,6 +204,10 @@ function variable_constraints_lb_dual(
     return model.variable_constraints_lb_dual
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+"""
 function variable_constraints_ub_dual(
     model::DualModel{
         <:Union{Function,Nothing},

src/model.jl

@@ -453,10 +453,18 @@ function has_free_initial_time(ocp::Model)::Bool
 end
 
 # Final time
+"""
+$(TYPEDSIGNATURES)
+
+"""
 function final_time(ocp::AbstractModel)
     throw(CTBase.UnauthorizedCall("You cannot get the final time with this function."))
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+"""
 function final_time(ocp::AbstractModel, variable::AbstractVector)
     throw(CTBase.UnauthorizedCall("You cannot get the final time with this function."))
 end