Merge pull request #10 from TaskBeacon/codex/audit-and-enrich-docstrings-in-numpy-style

Improve documentation for all modules

Author: zh1peng

psyflow/BlockUnit.py

@@ -7,11 +7,33 @@
 
 
 class BlockUnit:
-    """
-    A container that manages a block of experimental trials.
-
-    BlockUnit is responsible for generating trial conditions, running trials, 
-    executing lifecycle hooks, and collecting trial-level results.
+    """Block-level controller for trials.
+
+    This object generates trial conditions, executes each trial, and stores
+    metadata. It exposes hooks for custom start/end logic and summary methods.
+
+    Attributes
+    ----------
+    block_id : str
+        Identifier for the block.
+    block_idx : int
+        Index of this block in the experiment.
+    n_trials : int
+        Number of trials to execute.
+    settings : dict
+        Experiment settings container.
+    win : Any
+        PsychoPy window used for drawing.
+    kb : Any
+        PsychoPy keyboard used for responses.
+    seed : int
+        Seed used for randomisation.
+    conditions : list of Any or None
+        Ordered list of condition labels for each trial.
+    results : list of dict
+        Accumulated trial results after :meth:`run_trial`.
+    meta : dict
+        Additional block metadata such as start time and duration.
     """
 
     def __init__(

psyflow/LLM.py

@@ -202,9 +202,18 @@ def test(self, ping: str = "Hello", max_tokens: int = 1) -> Optional[str]:
         )
 
     def _count_tokens(self, text: str) -> int:
-        """
-        Return the token count for `text` under the currently-configured model.
-        Requires `tiktoken`.
+        """Count tokens for the active model.
+
+        Parameters
+        ----------
+        text : str
+            Text to be encoded.
+
+        Returns
+        -------
+        int
+            Number of tokens consumed by ``text`` under the current model's
+            tokenizer.
         """
         try:
             enc = tiktoken.encoding_for_model(self.model)

psyflow/StimBank.py

@@ -73,8 +73,12 @@ def decorator(func: Callable[[Any], Any]):
         return decorator
 
     def preload_all(self):
-        """
-        Instantiate all registered stimuli and cache them internally.
+        """Instantiate all registered stimuli.
+
+        Returns
+        -------
+        StimBank
+            The object itself for method chaining.
         """
         for name, factory in self._registry.items():
             if name not in self._instantiated:

psyflow/StimUnit.py

@@ -196,8 +196,15 @@ def send_trigger(self, trigger_code: int) -> "StimUnit":
         return self
 
     def log_unit(self) -> None:
-        """
-        Log the current state using PsychoPy's logging mechanism.
+        """Write the current trial state to PsychoPy logs.
+
+        All key-value pairs stored in :attr:`state` are emitted using
+        ``logging.data`` which allows post‑hoc reconstruction of each trial.
+
+        Examples
+        --------
+        >>> unit.set_state(response="space")
+        >>> unit.log_unit()
         """
         logging.data(f"[StimUnit] Data: {self.state}")
 
@@ -318,16 +325,27 @@ def close_fn(unit: 'StimUnit', key: str, rt: float):
         return self.on_response(list(keys), close_fn)
 
 
-    def run(self, 
+    def run(self,
             terminate_on_response: bool = True) -> "StimUnit":
-        """
-        Full logic loop for displaying stimulus, collecting response, handling timeout,
-        and logging with precision timing.
+        """Execute the full trial lifecycle.
+
+        This method draws all registered stimuli, handles response and timeout
+        events, executes registered hooks and logs the final state.
+
+        Parameters
+        ----------
+        terminate_on_response : bool, optional
+            If ``True`` the trial ends immediately once a response is
+            registered. Defaults to ``True``.
+
+        Returns
+        -------
+        StimUnit
+            The instance itself for chaining.
 
-        Parameters:
-        -----------
-        terminate_on_response : bool
-            Whether to terminate the trial upon receiving a response.
+        Examples
+        --------
+        >>> StimUnit("trial1", win).run()
         """
         self.set_state(global_time=core.getAbsTime())
 

psyflow/SubInfo.py

@@ -73,6 +73,12 @@ def collect(self, exit_on_cancel: bool = True) -> dict:
         dict or None
             Cleaned response dictionary with English field keys,
             or None if cancelled and exit_on_cancel is False.
+
+        Examples
+        --------
+        >>> cfg = {'subinfo_fields': [{'name': 'age', 'type': 'int'}]}
+        >>> info = SubInfo(cfg)
+        >>> info.collect(exit_on_cancel=False)
         """
         success = False
         responses = None

psyflow/TaskSettings.py

@@ -172,6 +172,11 @@ def from_dict(cls, config: dict):
         -------
         TaskSettings
             An initialized instance with config applied.
+
+        Examples
+        --------
+        >>> cfg = {'total_blocks': 2, 'total_trials': 20}
+        >>> TaskSettings.from_dict(cfg)
         """
         known_keys = set(f.name for f in cls.__dataclass_fields__.values())
         init_args = {k: v for k, v in config.items() if k in known_keys}

psyflow/TriggerSender.py

@@ -58,7 +58,16 @@ def send(self, code: Optional[int]):
         Parameters
         ----------
         code : int or None
-            The code to send. Skips if None and logs a warning.
+            The code to send. If ``None`` the method does nothing and logs a
+            warning.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        >>> sender.send(1)
         """
         if code is None:
             logging.warning("[Trigger] Skipping trigger send: code is None")

psyflow/cli.py

@@ -11,12 +11,22 @@
 @click.command()
 @click.argument("project_name", required=False)
 def climain(project_name):
-    """
-    psyflow-init [PROJECT_NAME]
+    """Create a new PsychoPy task from the bundled template.
+
+    Parameters
+    ----------
+    project_name : str, optional
+        Name of the project directory. If omitted or equal to the current
+        directory name, files are generated in place.
+
+    Returns
+    -------
+    None
+        Files are created on disk for their side effect.
 
-    - No args: initialize current dir (in-place)
-    - Arg == current dir name: same as no args
-    - Otherwise: create ./PROJECT_NAME
+    Examples
+    --------
+    >>> psyflow-init mytask
     """
     # 1. Locate our bundled template
     tmpl_dir = pkg_res.files("psyflow.templates") / "cookiecutter-psyflow"

psyflow/utils.py

@@ -1,7 +1,15 @@
 
 def show_ports():
-    """
-    List all available serial ports with descriptions.
+    """List all available serial ports.
+
+    The function prints a numbered list of connected serial ports with a short
+    description. It is mainly intended for quick troubleshooting when choosing
+    a port for trigger boxes or external devices.
+
+    Returns
+    -------
+    None
+        This function is executed for its side effect of printing to ``stdout``.
     """
     import serial.tools.list_ports
     ports = list(serial.tools.list_ports.comports())
@@ -17,14 +25,36 @@ def show_ports():
 
 from cookiecutter.main import cookiecutter
 import importlib.resources as pkg_res
+
+
 def taps(task_name: str, template: str = "cookiecutter-psyflow"):
-    # locate the template folder inside the installed package
+    """Generate a task skeleton using the bundled template.
+
+    Parameters
+    ----------
+    task_name : str
+        Name of the new task directory to create.
+    template : str, optional
+        Name of the template folder inside the package. Defaults to
+        ``"cookiecutter-psyflow"``.
+
+    Returns
+    -------
+    str
+        Path to the newly created project directory.
+
+    Examples
+    --------
+    >>> taps("mytask")
+    "mytask"
+    """
     tmpl_dir = pkg_res.files("psyflow") / template
     cookiecutter(
         str(tmpl_dir),
         no_input=True,
         extra_context={"project_name": task_name}
     )
+    return task_name
 
 
 from psychopy import visual, core
@@ -40,6 +70,11 @@ def count_down(win, seconds=3, **stim_kwargs):
         How many seconds to count down from.
     **stim_kwargs : dict
         Additional keyword arguments for TextStim (e.g., font, height, color).
+
+    Returns
+    -------
+    None
+        The countdown is shown on ``win`` for its side effect.
     """
     cd_clock = core.Clock()
     for i in reversed(range(1, seconds + 1)):
@@ -68,6 +103,11 @@ def load_config(config_file: str = 'config/config.yaml',
     -------
     dict
         Dictionary with structured configs.
+
+    Examples
+    --------
+    >>> cfg = load_config('config/config.yaml')
+    >>> cfg['task_config']['screen_width']
     """
     with open(config_file, encoding='utf-8') as f:
         config = yaml.safe_load(f)
@@ -103,15 +143,24 @@ def load_config(config_file: str = 'config/config.yaml',
 
 
 def initialize_exp(settings, screen_id: int = 1) -> Tuple[Window, keyboard.Keyboard]:
-    """
-    Initialize the experiment environment including window, keyboard, logging, and global quit key.
+    """Set up the PsychoPy window, keyboard and logging.
 
-    Parameters:
-        settings: Configuration object with display, logging, and task settings.
-        screen_id (int): ID of the screen to display the experiment window on.
+    Parameters
+    ----------
+    settings : Any
+        Configuration object with attributes describing window and logging
+        settings.
+    screen_id : int, optional
+        Monitor index to open the window on. Defaults to ``1``.
+
+    Returns
+    -------
+    tuple of (Window, Keyboard)
+        The created PsychoPy ``Window`` and ``Keyboard`` objects.
 
-    Returns:
-        Tuple[Window, Keyboard]: The initialized PsychoPy window and keyboard objects.
+    Examples
+    --------
+    >>> win, kb = initialize_exp(my_settings)
     """
     # === Window Setup ===
     mon = monitors.Monitor('tempMonitor')
@@ -178,9 +227,20 @@ def list_supported_voices(
     filter_lang: Optional[str] = None,
     human_readable: bool = False
 ):
-    """
-    – Returns raw voice dicts if human_readable=False.
-    – Prints a formatted table (including VoicePersonalities) if human_readable=True.
+    """Query available edge-tts voices.
+
+    Parameters
+    ----------
+    filter_lang : str, optional
+        Return only voices whose locale starts with this prefix.
+    human_readable : bool, optional
+        If ``True`` print a formatted table; otherwise return the raw list.
+
+    Returns
+    -------
+    list of dict or None
+        The raw voice dictionaries if ``human_readable`` is ``False``,
+        otherwise ``None``.
     """
     voices = asyncio.run(_list_supported_voices_async(filter_lang))
     if not human_readable: