MNT: polish event and flight-phase helper docstrings

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: MateusStano

rocketpy/simulation/events/event.py

@@ -25,7 +25,7 @@
 
 
 class Event:
-    """Event helper with trigger/callback execution and exact-time support.
+    """A rule that runs an action during a flight when a condition is met.
 
     An ``Event`` is the main way RocketPy reacts to conditions during a
     flight. It pairs a ``trigger`` predicate with a ``callback`` action: at
@@ -147,11 +147,11 @@ def __init__(  # pylint: disable=too-many-arguments
             slower with no gain in accuracy. Automatically forced to ``False``
             when ``sampling_rate`` is ``None``.
         changes_dynamics : bool, optional
-            Set to ``True`` when the callback changes the simulation dynamics or
-            any parameter affecting the ODE derivative. This includes mutating an
-            attribute of any simulation object, and using the
-            ``set_derivative``, ``start_flight_phase``, or ``terminate_flight``
-            commands. Defaults to ``False``.
+            Set to ``True`` when the callback changes anything that affects the
+            equations of motion. This includes changing an attribute of any
+            simulation object, and using the ``set_derivative``,
+            ``start_flight_phase``, or ``terminate_flight`` commands. Defaults to
+            ``False``.
         name : str, optional
             Human-readable identifier used in logs and debugging. Defaults to
             ``"Custom Event"``.
@@ -174,12 +174,11 @@ def __init__(  # pylint: disable=too-many-arguments
             - 3: Controller events
             - 4: Custom / user-defined events (default)
         needs : list of str or None, optional
-            Declares which expensive simulation values the event's trigger and
-            callback actually access. Valid keys are ``'state_dot'``,
-            ``'pressure'``, and ``'state_history'``. The default``None`` is
-            treated as an empty set and no expensive kwargs are computed.
-            Supply a list with the keys this event accesses so the runtime
-            computes them.
+            Which of the slower-to-compute simulation values the event's trigger
+            and callback actually use, so the rest are skipped. Valid keys are
+            ``'state_dot'``, ``'pressure'`` and ``'state_history'``. The default
+            ``None`` means none of them are computed. List the keys your event
+            uses to have them provided in ``kwargs``.
 
         See Also
         --------
@@ -306,6 +305,9 @@ def __call__(self, trigger_only=False, callback_only=False, reset=True, **kwargs
             If True, only execute the callback without evaluating the trigger
             condition. The exact time function and disable_on function are also
             called.
+        reset : bool, optional
+            If True (default), reset the event's queued commands (via
+            ``_reset_commands``) before evaluating the trigger.
         kwargs : dict
             Keyword arguments passed to the trigger and callback functions.
 

rocketpy/simulation/events/event_builders.py

@@ -160,7 +160,7 @@ def apogee_event_exact_time_function(state, **_kwargs):
     ----------
     state : array_like
         Interpolated flight state vector without time.
-    **kwargs : dict
+    **_kwargs : dict
         Event context (unused here).
 
     Returns

rocketpy/simulation/helpers/event_calling.py

@@ -30,11 +30,29 @@ def build_event_kwargs(
 
     Parameters
     ----------
+    flight : Flight
+        Flight instance whose rocket, environment and sensors are exposed.
+    time : float
+        Current simulation time.
+    state : array_like
+        Current flight state vector.
+    step_size : float
+        Size of the current integration step.
+    phase : FlightPhase
+        Active flight phase, providing the state derivative.
+    rollback : bool, optional
+        Whether this call happens during a rollback; shifts the state-history
+        window by one extra step. Defaults to False.
     needs : frozenset of str, optional
         Union of ``Event.needs`` across all events that will consume the
         returned dict. Only keys present in ``needs`` are computed for the
         expensive values: ``state_dot``, ``pressure``, ``state_history``.
         Defaults to empty (compute nothing expensive).
+
+    Returns
+    -------
+    dict
+        Keyword arguments consumed by event triggers and callbacks.
     """
     kwargs = {
         "time": time,
@@ -72,10 +90,25 @@ def update_overshootable_event_kwargs(
 
     Parameters
     ----------
+    flight : Flight
+        Flight instance whose environment is used to recompute derived values.
+    phase : FlightPhase
+        Active flight phase, providing the state derivative.
+    event_kwargs : dict
+        Kwargs dict (from :func:`build_event_kwargs`) updated in place.
+    interpolated_time : float
+        Interpolated time of the overshootable node.
+    interpolated_state : array_like
+        Interpolated flight state at the node.
     needs : frozenset of str, optional
         Union of ``Event.needs`` across all overshootable events at this node.
         Expensive values are skipped when absent from ``needs``. Defaults to
         empty (compute nothing expensive).
+
+    Returns
+    -------
+    dict
+        The updated ``event_kwargs``.
     """
     event_kwargs["time"] = interpolated_time
     event_kwargs["state"] = interpolated_state

rocketpy/simulation/helpers/event_commands.py

@@ -28,6 +28,9 @@ def apply_event_commands(
         Index of the current flight phase.
     node_index : int
         Index of the current time node.
+    command_time : float
+        Simulation time used to apply the commands when the event does not
+        provide an exact time.
 
     Returns
     -------
@@ -70,10 +73,6 @@ def apply_rollback_command(flight, time, state):
     ----------
     flight : Flight
         Flight instance being updated.
-    event_results : dict
-        Result payload returned by the event system.
-    phase : _FlightPhase
-        Current flight phase.
     time : float
         Interpolated simulation time to restore.
     state : array_like
@@ -94,6 +93,8 @@ def apply_disable_commands(_, event_results, node_index, event, phase, time):
 
     Parameters
     ----------
+    _ : Flight
+        Flight instance (unused; accepted for a uniform command signature).
     event_results : dict
         Result payload returned by the event system.
     node_index : int
@@ -102,6 +103,8 @@ def apply_disable_commands(_, event_results, node_index, event, phase, time):
         Event currently being processed.
     phase : _FlightPhase
         Current flight phase.
+    time : float
+        Simulation time at which the events are disabled.
 
     Returns
     -------
@@ -144,6 +147,8 @@ def apply_enable_commands(flight, event_results, node_index, event, phase, time)
 
     Parameters
     ----------
+    flight : Flight
+        Flight instance being updated.
     event_results : dict
         Result payload returned by the event system.
     node_index : int
@@ -152,6 +157,8 @@ def apply_enable_commands(flight, event_results, node_index, event, phase, time)
         Event currently being processed.
     phase : _FlightPhase
         Current flight phase.
+    time : float
+        Simulation time at which the events are enabled.
 
     Returns
     -------
@@ -260,6 +267,8 @@ def apply_new_phase_or_derivative(
         Index of the current flight phase.
     node_index : int
         Index of the current time node.
+    time : float
+        Simulation time at which the new phase or derivative takes effect.
 
     Returns
     -------
@@ -317,6 +326,8 @@ def apply_termination(flight, event_results, phase, phase_index, node_index, tim
         Index of the current flight phase.
     node_index : int
         Index of the current time node.
+    time : float
+        Simulation time at which the flight is terminated.
 
     Returns
     -------
@@ -358,12 +369,10 @@ def apply_event_list_updates(flight, event_results, phase, time):
         Flight instance being updated.
     event_results : dict
         Result payload returned by the event system.
-    node_index : int
-        Index of the current time node.
-    event : Event
-        Event currently being processed.
     phase : _FlightPhase
         Current flight phase.
+    time : float
+        Simulation time at which the new events are scheduled.
 
     Returns
     -------

rocketpy/simulation/helpers/flight_phase.py

@@ -276,6 +276,9 @@ def add_phase(
         name : str, optional
             A descriptive name to identify the phase in logs and
             debug output. Default is None.
+        **kwargs
+            Additional keyword arguments forwarded to the ``_FlightPhase``
+            constructor (e.g. ``parachute``).
 
         Returns
         -------