Merge pull request #2324 from sathvikbhagavan/sb/docstrings

docs: Fix Systems docstrings
SciML · Oct 22, 2023 · 3d428f7 · 3d428f7
2 parents d31b252 + b9beec3
commit 3d428f7
Show file tree

Hide file tree

Showing 8 changed files with 101 additions and 99 deletions.
diff --git a/src/systems/diffeqs/odesystem.jl b/src/systems/diffeqs/odesystem.jl
@@ -24,7 +24,7 @@ eqs = [D(x) ~ σ*(y-x),
 """
 struct ODESystem <: AbstractODESystem
     """
-    tag: a tag for the system. If two systems have the same tag, then they are
+    A tag for the system. If two systems have the same tag, then they are
     structurally identical.
     """
     tag::UInt
@@ -35,8 +35,8 @@ struct ODESystem <: AbstractODESystem
     """
     Dependent (state) variables. Must not contain the independent variable.
 
-    N.B.: If torn_matching !== nothing, this includes all variables. Actual
-    ODE states are determined by the SelectedState() entries in `torn_matching`.
+    N.B.: If `torn_matching !== nothing`, this includes all variables. Actual
+    ODE states are determined by the `SelectedState()` entries in `torn_matching`.
     """
     states::Vector
     """Parameter variables. Must not contain the independent variable."""
@@ -65,86 +65,86 @@ struct ODESystem <: AbstractODESystem
     """
     ctrl_jac::RefValue{Any}
     """
-    `Wfact` matrix. Note: this field will not be defined until
+    Note: this field will not be defined until
     [`generate_factorized_W`](@ref) is called on the system.
     """
     Wfact::RefValue{Matrix{Num}}
     """
-    `Wfact_t` matrix. Note: this field will not be defined until
+    Note: this field will not be defined until
     [`generate_factorized_W`](@ref) is called on the system.
     """
     Wfact_t::RefValue{Matrix{Num}}
     """
-    Name: the name of the system
+    The name of the system.
     """
     name::Symbol
     """
-    systems: The internal systems. These are required to have unique names.
+    The internal systems. These are required to have unique names.
     """
     systems::Vector{ODESystem}
     """
-    defaults: The default values to use when initial conditions and/or
+    The default values to use when initial conditions and/or
     parameters are not supplied in `ODEProblem`.
     """
     defaults::Dict
     """
-    torn_matching: Tearing result specifying how to solve the system.
+    Tearing result specifying how to solve the system.
     """
     torn_matching::Union{Matching, Nothing}
     """
-    connector_type: type of the system
+    Type of the system.
     """
     connector_type::Any
     """
-    preface: inject assignment statements before the evaluation of the RHS function.
+    Inject assignment statements before the evaluation of the RHS function.
     """
     preface::Any
     """
-    continuous_events: A `Vector{SymbolicContinuousCallback}` that model events.
+    A `Vector{SymbolicContinuousCallback}` that model events.
     The integrator will use root finding to guarantee that it steps at each zero crossing.
     """
     continuous_events::Vector{SymbolicContinuousCallback}
     """
-    discrete_events: A `Vector{SymbolicDiscreteCallback}` that models events. Symbolic
+    A `Vector{SymbolicDiscreteCallback}` that models events. Symbolic
     analog to `SciMLBase.DiscreteCallback` that executes an affect when a given condition is
     true at the end of an integration step.
     """
     discrete_events::Vector{SymbolicDiscreteCallback}
     """
-    metadata: metadata for the system, to be used by downstream packages.
+    Metadata for the system, to be used by downstream packages.
     """
     metadata::Any
     """
-    gui_metadata: metadata for MTK GUI.
+    Metadata for MTK GUI.
     """
     gui_metadata::Union{Nothing, GUIMetadata}
     """
-    tearing_state: cache for intermediate tearing state
+    Cache for intermediate tearing state.
     """
     tearing_state::Any
     """
-    substitutions: substitutions generated by tearing.
+    Substitutions generated by tearing.
     """
     substitutions::Any
     """
-    complete: if a model `sys` is complete, then `sys.x` no longer performs namespacing.
+    If a model `sys` is complete, then `sys.x` no longer performs namespacing.
     """
     complete::Bool
     """
-    discrete_subsystems: a list of discrete subsystems.
+    A list of discrete subsystems.
     """
     discrete_subsystems::Any
     """
-    unknown_states: a list of actual states needed to be solved by solvers. Only
+    A list of actual states needed to be solved by solvers. Only
     used for ODAEProblem.
     """
     unknown_states::Union{Nothing, Vector{Any}}
     """
-    split_idxs: a vector of vectors of indices for the split parameters.
+    A vector of vectors of indices for the split parameters.
     """
     split_idxs::Union{Nothing, Vector{Vector{Int}}}
     """
-    parent: the hierarchical parent system before simplification.
+    The hierarchical parent system before simplification.
     """
     parent::Any
 

diff --git a/src/systems/diffeqs/sdesystem.jl b/src/systems/diffeqs/sdesystem.jl
@@ -28,7 +28,7 @@ noiseeqs = [0.1*x,
 """
 struct SDESystem <: AbstractODESystem
     """
-    tag: a tag for the system. If two systems have the same tag, then they are
+    A tag for the system. If two systems have the same tag, then they are
     structurally identical.
     """
     tag::UInt
@@ -66,57 +66,57 @@ struct SDESystem <: AbstractODESystem
     """
     ctrl_jac::RefValue{Any}
     """
-    `Wfact` matrix. Note: this field will not be defined until
+    Note: this field will not be defined until
     [`generate_factorized_W`](@ref) is called on the system.
     """
     Wfact::RefValue
     """
-    `Wfact_t` matrix. Note: this field will not be defined until
+    Note: this field will not be defined until
     [`generate_factorized_W`](@ref) is called on the system.
     """
     Wfact_t::RefValue
     """
-    Name: the name of the system
+    The name of the system.
     """
     name::Symbol
     """
-    Systems: the internal systems. These are required to have unique names.
+    The internal systems. These are required to have unique names.
     """
     systems::Vector{SDESystem}
     """
-    defaults: The default values to use when initial conditions and/or
+    The default values to use when initial conditions and/or
     parameters are not supplied in `ODEProblem`.
     """
     defaults::Dict
     """
-    type: type of the system
+    Type of the system.
     """
     connector_type::Any
     """
-    continuous_events: A `Vector{SymbolicContinuousCallback}` that model events.
+    A `Vector{SymbolicContinuousCallback}` that model events.
     The integrator will use root finding to guarantee that it steps at each zero crossing.
     """
     continuous_events::Vector{SymbolicContinuousCallback}
     """
-    discrete_events: A `Vector{SymbolicDiscreteCallback}` that models events. Symbolic
+    A `Vector{SymbolicDiscreteCallback}` that models events. Symbolic
     analog to `SciMLBase.DiscreteCallback` that executes an affect when a given condition is
     true at the end of an integration step.
     """
     discrete_events::Vector{SymbolicDiscreteCallback}
     """
-    metadata: metadata for the system, to be used by downstream packages.
+    Metadata for the system, to be used by downstream packages.
     """
     metadata::Any
     """
-    gui_metadata: metadata for MTK GUI.
+    Metadata for MTK GUI.
     """
     gui_metadata::Union{Nothing, GUIMetadata}
     """
-    complete: if a model `sys` is complete, then `sys.x` no longer performs namespacing.
+    If a model `sys` is complete, then `sys.x` no longer performs namespacing.
     """
     complete::Bool
     """
-    parent: the hierarchical parent system before simplification.
+    The hierarchical parent system before simplification.
     """
     parent::Any
 

diff --git a/src/systems/discrete_system/discrete_system.jl b/src/systems/discrete_system/discrete_system.jl
@@ -25,7 +25,7 @@ eqs = [D(x) ~ σ*(y-x),
 """
 struct DiscreteSystem <: AbstractTimeDependentSystem
     """
-    tag: a tag for the system. If two systems have the same tag, then they are
+    A tag for the system. If two systems have the same tag, then they are
     structurally identical.
     """
     tag::UInt
@@ -46,48 +46,48 @@ struct DiscreteSystem <: AbstractTimeDependentSystem
     """Observed states."""
     observed::Vector{Equation}
     """
-    Name: the name of the system
+    The name of the system
     """
     name::Symbol
     """
-    systems: The internal systems. These are required to have unique names.
+    The internal systems. These are required to have unique names.
     """
     systems::Vector{DiscreteSystem}
     """
-    defaults: The default values to use when initial conditions and/or
+    The default values to use when initial conditions and/or
     parameters are not supplied in `DiscreteProblem`.
     """
     defaults::Dict
     """
-    preface: inject assignment statements before the evaluation of the RHS function.
+    Inject assignment statements before the evaluation of the RHS function.
     """
     preface::Any
     """
-    connector_type: type of the system
+    Type of the system.
     """
     connector_type::Any
     """
-    metadata: metadata for the system, to be used by downstream packages.
+    Metadata for the system, to be used by downstream packages.
     """
     metadata::Any
     """
-    gui_metadata: metadata for MTK GUI.
+    Metadata for MTK GUI.
     """
     gui_metadata::Union{Nothing, GUIMetadata}
     """
-    tearing_state: cache for intermediate tearing state
+    Cache for intermediate tearing state.
     """
     tearing_state::Any
     """
-    substitutions: substitutions generated by tearing.
+    Substitutions generated by tearing.
     """
     substitutions::Any
     """
-    complete: if a model `sys` is complete, then `sys.x` no longer performs namespacing.
+    If a model `sys` is complete, then `sys.x` no longer performs namespacing.
     """
     complete::Bool
     """
-    parent: the hierarchical parent system before simplification.
+    The hierarchical parent system before simplification.
     """
     parent::Any
 

diff --git a/src/systems/jumps/jumpsystem.jl b/src/systems/jumps/jumpsystem.jl
@@ -49,7 +49,7 @@ j₃      = MassActionJump(2*β+γ, [R => 1], [S => 1, R => -1])
 """
 struct JumpSystem{U <: ArrayPartition} <: AbstractTimeDependentSystem
     """
-    tag: a tag for the system. If two systems have the same tag, then they are
+    A tag for the system. If two systems have the same tag, then they are
     structurally identical.
     """
     tag::UInt
@@ -66,38 +66,39 @@ struct JumpSystem{U <: ArrayPartition} <: AbstractTimeDependentSystem
     ps::Vector
     """Array variables."""
     var_to_name::Any
+    """Observed states."""
     observed::Vector{Equation}
-    """The name of the system. . These are required to have unique names."""
+    """The name of the system."""
     name::Symbol
-    """The internal systems."""
+    """The internal systems. These are required to have unique names."""
     systems::Vector{JumpSystem}
     """
-    defaults: The default values to use when initial conditions and/or
+    The default values to use when initial conditions and/or
     parameters are not supplied in `ODEProblem`.
     """
     defaults::Dict
     """
-    type: type of the system
+    Type of the system.
     """
     connector_type::Any
     """
-    discrete_events: A `Vector{SymbolicDiscreteCallback}` that models events. Symbolic
+    A `Vector{SymbolicDiscreteCallback}` that models events. Symbolic
     analog to `SciMLBase.DiscreteCallback` that executes an affect when a given condition is
-    true at the end of an integration step. *Note, one must make sure to call
+    true at the end of an integration step. Note, one must make sure to call
     `reset_aggregated_jumps!(integrator)` if using a custom affect function that changes any
-    state value or parameter.*
+    state value or parameter.
     """
     discrete_events::Vector{SymbolicDiscreteCallback}
     """
-    metadata: metadata for the system, to be used by downstream packages.
+    Metadata for the system, to be used by downstream packages.
     """
     metadata::Any
     """
-    gui_metadata: metadata for MTK GUI.
+    Metadata for MTK GUI.
     """
     gui_metadata::Union{Nothing, GUIMetadata}
     """
-    complete: if a model `sys` is complete, then `sys.x` no longer performs namespacing.
+    If a model `sys` is complete, then `sys.x` no longer performs namespacing.
     """
     complete::Bool