From e8d0e45bfb2ec1165f56d2fa573de6874c87dda0 Mon Sep 17 00:00:00 2001
From: Markus Rosenstihl <markus.rosenstihl@pkm.tu-darmstadt.de>
Date: Thu, 9 Jul 2026 16:42:03 +0200
Subject: [PATCH] doc string

---
 src/damaris/data/DataPool.py | 50 ++++++++++++++++++++++++++++++++++--
 1 file changed, 48 insertions(+), 2 deletions(-)

diff --git a/src/damaris/data/DataPool.py b/src/damaris/data/DataPool.py
index 9fd436f..797b023 100644
--- a/src/damaris/data/DataPool.py
+++ b/src/damaris/data/DataPool.py
@@ -108,6 +108,52 @@ class DataPool(collections.abc.MutableMapping):
         self.__registered_listeners=None
 
     def write_hdf5(self,hdffile,where="/",name="data_pool", complib=None, complevel=None):
+        """
+        Writes the content of a DataPool object to an HDF5 file using the `tables` library.
+
+        This method serializes the entire content of the data pool into an HDF5 file, creating
+        appropriate groups and arrays based on the keys and values stored in the data pool.
+        Nested storage paths are supported, and group or array names are
+        converted into valid HDF5 names. Paths are prepended with "dir_", results with "dict_".
+        If duplicate names arise, extensions (like `_001`, `_002`)
+        are appended to ensure uniqueness.
+
+        Parameters:
+        hdffile : str | bytes | tables.File
+            Path to the HDF5 file or an already open `tables.File` object where the
+            data should be written. Strings or bytes are interpreted as file paths.
+
+        where : str, optional
+            The root HDF5 group path under which the data pool will be stored.
+            Defaults to "/".
+
+        name : str, optional
+            The name of the root HDF5 group under which the data pool is saved.
+            Defaults to "data_pool".
+
+        complib : str, optional
+            Compression library to be used when creating HDF5 arrays. Optional, defaults
+            to None, meaning no compression is applied.
+
+        complevel : int, optional
+            Compression level to use when applying compression. Has no effect if `complib`
+            is set to None.
+
+        Raises:
+        Exception
+            If `hdffile` is neither a string nor a valid `tables.File` object.
+
+        Notes:
+        - This method assumes that the content of the data pool does not change during the
+          write operation.
+        - Keys in the data pool starting with "__" (double underscores) are skipped.
+        - If a key contains nested paths (e.g., "group1/subgroup2/item"), intermediate
+          groups are created as necessary.
+        - Group or array names are converted to valid HDF5 names, and name conflicts
+          are resolved by appending extensions (e.g., "_001").
+        - Errors during the writing process are logged to the console, and traceback
+          information is displayed for debugging purposes.
+        """
         if isinstance(hdffile, (bytes, str)):
             dump_file=tables.open_file(hdffile, mode="a")
         elif isinstance(hdffile,tables.File):
@@ -194,7 +240,7 @@ class DataPool(collections.abc.MutableMapping):
 
     def read_from_hdf(self, hdffile, where="/data_pool"):
         """
-        Read data from HDF5 file and populate the DataPool.
+        Read specified data from HDF5 file and populate the DataPool.
         
         Parameters:
         - hdffile: HDF5 file object or filename (bytes/str)
@@ -337,7 +383,7 @@ class DataPool(collections.abc.MutableMapping):
     @classmethod
     def load_hdf5(cls, filename):
         """
-        Load a DAMARIS HDF5 file and return DataPool and metadata.
+        Load a complete DAMARIS HDF5 file and return DataPool and metadata, including scripts.
         
         Parameters:
         - filename: Path to HDF5 file