Add comprehensive docstrings for key functions and types (#33)

* Add comprehensive docstrings for key functions and types

- apply_subsystem_noise\!: Stochastic noise application
- discrete_event_condition: Event trigger conditions
- apply_discrete_event\!: Event handling and state modification
- get_tag, get_params, get_states: Accessor functions
- ConnectionMatrices: Multi-type connection container with diagram
- ConnectionMatrix: Block matrix structure with ASCII visualization
- graph_ode\!: Core simulation function with detailed flow diagram

* Update src/GraphDynamics.jl

* Update src/GraphDynamics.jl

* Update src/GraphDynamics.jl

* Update src/GraphDynamics.jl

* Update src/GraphDynamics.jl

* Update src/graph_solve.jl

* Update src/graph_solve.jl

---------

Co-authored-by: Helmut Strey <[email protected]>
Co-authored-by: Mason Protter <[email protected]>

Author: 3 people

src/GraphDynamics.jl

@@ -153,8 +153,55 @@ struct Subsystem{T, Eltype, States, Params}
     params::SubsystemParams{T, Params}
 end
 
+"""
+    get_tag(subsystem::Subsystem{T}) = T
+    get_tag(states::SubsystemStates{T}) = T
+    get_tag(params::SubsystemParams{T}) = T
+    get_tag(::Type{<:Subsystem{T}}) = T
+
+Extract the type tag `T` from a subsystem or its components.
+
+The tag identifies the subsystem type and is used for dispatch and organization.
+
+# Examples
+```julia
+particle = Subsystem{Particle}(states=(x=1.0, v=0.0), params=(m=2.0,))
+get_tag(particle)  # returns Particle
+get_tag(typeof(particle))  # returns Particle
+```
+"""
 function get_tag end
+"""
+    get_params(subsystem::Subsystem) -> SubsystemParams
+
+Extract the parameters from a subsystem.
+
+Returns a `SubsystemParams` object containing the non-dynamical parameters
+(constants like mass, charge, spring constants, etc.) of the subsystem.
+
+# Example
+```julia
+sys = Subsystem{Oscillator}(states=(x=1.0, v=0.0), params=(k=2.0, m=1.0))
+params = get_params(sys)  # SubsystemParams{Oscillator}(k=2.0, m=1.0)
+params.k  # 2.0
+```
+"""
 function get_params end
+"""
+    get_states(subsystem::Subsystem) -> SubsystemStates
+
+Extract the state variables from a subsystem.
+
+Returns a `SubsystemStates` object containing the dynamical state variables
+(position, velocity, concentrations, etc.) that evolve over time.
+
+# Example
+```julia
+sys = Subsystem{Oscillator}(states=(x=1.0, v=0.0), params=(k=2.0, m=1.0))
+states = get_states(sys)  # SubsystemStates{Oscillator}(x=1.0, v=0.0)
+states.x  # 1.0
+```
+"""
 function get_states end
 
 """
@@ -220,6 +267,27 @@ defaults to false, but users may add methods to this function if they have subsy
 subsystem_differential_requires_inputs(::Type{T}) where {T} = true
 subsystem_differential_requires_inputs(::Subsystem{T}) where {T} = subsystem_differential_requires_inputs(T)
 
+"""
+    apply_subsystem_noise!(vstate, subsystem, t)
+
+Apply stochastic noise to a subsystem's state at time `t`.
+
+This function modifies the noise terms for a subsystem's stochastic differential equation.
+By default, it does nothing (no noise). Override this for stochastic subsystems.
+
+# Arguments
+- `vstate`: A view into the noise vector to be modified
+- `subsystem`: The `Subsystem` instance whose noise is being computed
+- `t`: Current time
+
+# Example
+```julia
+function GraphDynamics.apply_subsystem_noise!(vstate, sys::Subsystem{BrownianParticle}, t)
+    # No noise in position, so we don't modify vstate[:x]
+    vstate[:v] = sys.σ    # White noise in velocity with amplitude σ
+end
+```
+"""
 function apply_subsystem_noise!(vstate, subsystem, t)
     nothing
 end
@@ -235,6 +303,32 @@ end
 function continuous_event_condition end
 function apply_continuous_event! end
 function discrete_event_condition end
+"""
+    apply_discrete_event!(integrator, sview, pview, subsystem, F[, input])
+    apply_discrete_event!(integrator, sview_src, pview_src, sview_dst, pview_dst, 
+                         connection_rule, sys_src, sys_dst[, input_src, input_dst])
+
+Apply a discrete event to modify subsystem states or parameters.
+
+This function is called when `discrete_event_condition` returns `true`.
+
+# Arguments
+- `integrator`: The ODE/SDE integrator
+- `sview`/`pview`: Views into states/params to be modified
+- `subsystem`: The subsystem experiencing the event
+- `F`: `ForeachConnectedSubsystem` for accessing connected subsystems
+- `input`: Optional input from connected subsystems
+- For connection events: views and systems for both source and destination
+
+# Example
+```julia
+function GraphDynamics.apply_discrete_event!(integrator, sview, pview, 
+                                            sys::Subsystem{Ball}, F)
+    # Bounce: reverse velocity
+    sview[:v] = -sys.restitution * sview[:v]
+end
+```
+"""
 function apply_discrete_event! end
 
 

src/graph_solve.jl

@@ -1,3 +1,42 @@
+"""
+    graph_ode!(du, u, p, t)
+
+Core ODE function for graph dynamics simulation.
+
+Computes derivatives for all subsystems in the graph, handling:
+1. Partitioning states by subsystem type
+2. Computing inputs from connections
+3. Applying subsystem differential equations
+
+# Arguments
+- `du`: Derivative vector (modified in-place)
+- `u`: Current state vector
+- `p`: Parameters with fields:
+  - `params_partitioned`: Parameters grouped by subsystem type
+  - `connection_matrices`: Connection structure
+  - `scheduler`: Parallelization scheduler
+  - `partition_plan`: Information for how to partition u and du into vectors of SubsystemStates grouped by subsystem type 
+- `t`: Current time
+
+# Flow Diagram
+```
+u (flat state vector)
+    │
+    ├─── partitioned ──→ states[Type1][1..n]
+    │                    states[Type2][1..m]
+    │                    states[Type3][1..k]
+    │
+    ├─── for each subsystem i of type T:
+    │    │
+    │    ├── calculate_inputs from connections
+    │    │   └── Σ connection_rule(src → dst)
+    │    │
+    │    └── subsystem_differential(sys, input, t)
+    │        └── writes to du[i]
+    │
+    └─── du (flat derivative vector)
+```
+"""
 #----------------------------------------------------------
 function graph_ode!(du,
                     u,