added extensive doc string to main classes

src/damaris/gui/DamarisGUI.py

@@ -1310,8 +1310,23 @@ class start_browser( threading.Thread ):
 
 
 class LogWindow:
-    """
-    writes messages to the log window
+    """Manages the application log window.
+
+    Provides a timestamped, scrollable text view for application messages.
+    Messages are dispatched via ``gobject.idle_add`` to keep the GTK main
+    loop responsive.
+
+    Args:
+        xml_gui: The :class:`gtk.Builder` instance containing the GUI widgets.
+        damaris_gui: Reference to the main :class:`DamarisGUI` application.
+
+    Attributes:
+        textview (:class:`gtk.TextView`): The monospaced text view widget.
+        textbuffer (:class:`gtk.TextBuffer`): The buffer backing the text view.
+
+    Examples:
+        >>> log = LogWindow(xml_gui, damaris_gui)
+        >>> log("Application started")
     """
 
     def __init__( self, xml_gui, damaris_gui ):
@@ -1356,9 +1371,55 @@ class LogWindow:
 
 
 class ScriptWidgets:
+    """Manages experiment and result script editing widgets.
+
+    Provides two syntax-highlighted, auto-completing text views for editing
+    DAMARIS experiment and result scripts. Handles file open/save dialogs,
+    toolbar state management, line/column indicators, and search functionality.
+
+    Args:
+        xml_gui: The :class:`gtk.Builder` instance containing the GUI widgets.
+        outer_space: Reference to the parent application (typically
+            :class:`DamarisGUI`) that owns this widget set.
+
+    Attributes:
+        editing_state (bool): ``True`` if scripts are editable, ``False`` during
+            experiment execution.
+        exp_script_filename (str or None): Path to the currently loaded
+            experiment script file.
+        res_script_filename (str or None): Path to the currently loaded
+            result script file.
+        experiment_script_textview (:class:`gtksourceview2.View`): Text view
+            for the experiment script.
+        data_handling_textview (:class:`gtksourceview2.View`): Text view for
+            the result script.
+
+    Public Methods:
+        set_scripts: Replace script buffer contents.
+        get_scripts: Retrieve current script text from both buffers.
+        enable_editing: Re-enable script editing.
+        disable_editing: Lock scripts during experiment execution.
+        open_file: Open a script file via file chooser dialog.
+        open_hdf5: Load data and scripts from an HDF5 file.
+        save_file: Save the current script to its associated file.
+        save_file_as: Save the current script with a new filename.
+        save_all_files: Save both experiment and result scripts.
+        new_file: Clear the current script buffer.
+        check_script: Compile-check the current script for syntax errors.
+        undo / redo: Undo/redo text edits.
+        search: Open the search-and-replace dialog.
+    """
     def __init__( self, xml_gui, outer_space ):
-        """
-        initialize text widgets with text
+        """Initialize text widgets with syntax highlighting and completion.
+
+        Sets up two :class:`gtksourceview2.View` instances with Python
+        syntax highlighting, keyword auto-completion, line numbers, and
+        smart indentation. Connects text buffer signals to toolbar and
+        status bar update handlers.
+
+        Args:
+            xml_gui: The :class:`gtk.Builder` instance containing the GUI widgets.
+            outer_space: Reference to the parent application.
         """
         self.xml_gui = xml_gui
         self.outer_space = outer_space
@@ -2848,9 +2909,54 @@ pygobject version %(pygobject)s
 
 
 class MonitorWidgets:
+    """Manages the matplotlib-based data visualization panel.
+
+    Provides an interactive plot canvas with zoom, pan, scaling controls,
+    a data source selector, and real-time updates from the DAMARIS data pool.
+    Supports :class:`Accumulation`, :class:`ADC_Result`, and
+    :class:`MeasurementResult` data types with automatic axis rescaling,
+    error bars, and statistics overlays.
+
+    Args:
+        xml_gui: The :class:`gtk.Builder` instance containing the GUI widgets.
+
+    Attributes:
+        matplot_figure (:class:`matplotlib.figure.Figure`): The underlying
+            matplotlib figure.
+        matplot_axes (:class:`matplotlib.axes.Axes`): The plot axes.
+        matplot_canvas (:class:`matplotlib.backends.backend_gtk3.FigureCanvas`):
+            The GTK canvas embedding the figure.
+        matplot_toolbar (:class:`matplotlib.backends.backend_gtk3.NavigationToolbar2GTK3`):
+            The navigation toolbar with pan/zoom/cursor controls.
+        data_pool (:class:`damaris.data.DataPool` or None): The data pool
+            being observed for real-time updates.
+        displayed_data (list): ``[data_name, data_object]`` of the currently
+            selected data, or ``[None, None]``.
+
+    Public Methods:
+        observe_data_pool: Register a listener and begin observing a data pool.
+        source_list_reset: Reset the data source selector tree.
+        source_list_add: Add a data source entry to the selector tree.
+        source_list_remove: Remove a data source entry from the selector tree.
+        source_list_current: Get the currently selected data source name.
+        clear_display: Clear all plot elements and reset axes.
+        update_display: Redraw the plot with current data.
+        renew_display: Clear and redraw the plot with current data.
+        save_display_data_as_text: Export displayed data to a CSV file.
+        toggle_cursor: Toggle the matplotlib crosshair cursor.
+        copy_canvas_as_png: Copy the plot as a PNG image to the clipboard.
+        copy_canvas_as_svg: Copy the plot as SVG text to the clipboard.
+    """
     def __init__( self, xml_gui ):
-        """
-        initialize matplotlib widgets and stuff around
+        """Initialize matplotlib widgets, canvas, toolbar, and source selector.
+
+        Creates a :class:`matplotlib.figure.Figure` with linear x/y axes,
+        embeds it in a GTK canvas, attaches a navigation toolbar with a
+        custom crosshair toggle button, and builds a hierarchical source
+        selector :class:`gtk.TreeStore`.
+
+        Args:
+            xml_gui: The :class:`gtk.Builder` instance containing the GUI widgets.
         """
 
         self.xml_gui = xml_gui
@@ -3953,14 +4059,55 @@ class MonitorWidgets:
 
 
 class ScriptInterface:
-    """
-    texts or code objects are executed as experiment and result script the backend is started with sufficient arguments
+    """Executes experiment and result scripts, coordinating with the DAMARIS backend.
+
+    Manages the lifecycle of experiment and result script execution. Depending
+    on whether a backend executable is provided, it either uses
+    :class:`BackendDriver.BackendDriver` to spawn an external process or falls
+    back to in-process :class:`ExperimentWriter` and :class:`ResultReader`
+    components. A shared :class:`DataPool` is used for communication between
+    scripts and the GUI.
+
+    Args:
+        exp_script (str or None): Python source code for the experiment script.
+        res_script (str or None): Python source code for the result script.
+        backend_executable (str or None): Path to the DAMARIS backend executable.
+            If ``None``, in-process execution is used.
+        spool_dir (str): Directory for inter-process communication spool files.
+            Defaults to ``"spool"``.
+        clear_jobs (bool): Clear pending jobs on startup. Defaults to ``True``.
+        clear_results (bool): Clear pending results on startup. Defaults to ``True``.
+        log_callback (callable or None): Optional callback for log messages.
+
+    Attributes:
+        data (:class:`damaris.data.DataPool`): Shared data pool for
+            experiment/result communication.
+        exp_handling (:class:`ExperimentHandling.ExperimentHandling` or None):
+            The running experiment handler thread.
+        res_handling (:class:`ResultHandling.ResultHandling` or None):
+            The running result handler thread.
+        back_driver (:class:`BackendDriver.BackendDriver` or None):
+            The backend process driver, if a backend executable was provided.
+
+    Public Methods:
+        runScripts: Start experiment, result, and backend handlers.
     """
 
     def __init__( self, exp_script=None, res_script=None, backend_executable=None, spool_dir="spool", clear_jobs=True,
                   clear_results=True, log_callback=None ):
-        """
-        run experiment scripts and result scripts
+        """Initialize the script execution environment.
+
+        Sets up the data pool, experiment writer, result reader, and optional
+        backend driver based on the provided configuration.
+
+        Args:
+            exp_script (str or None): Python source code for the experiment script.
+            res_script (str or None): Python source code for the result script.
+            backend_executable (str or None): Path to the DAMARIS backend executable.
+            spool_dir (str): Directory for inter-process communication spool files.
+            clear_jobs (bool): Clear pending jobs on startup.
+            clear_results (bool): Clear pending results on startup.
+            log_callback (callable or None): Optional callback for log messages.
         """
 
         self.exp_script = exp_script
@@ -3995,6 +4142,13 @@ class ScriptInterface:
         self.data = DataPool( )
 
     def runScripts( self ):
+        """Start experiment, result, and backend handler threads.
+
+        Creates and starts :class:`ExperimentHandling` and
+        :class:`ResultHandling` threads, and optionally starts the backend
+        driver process. Waits for the backend to report a valid PID before
+        proceeding.
+        """
         try:
             # get script engines
             self.exp_handling = self.res_handling = None