finishing touches on file.py docstring

src/robofish/io/file.py

@@ -79,33 +79,46 @@ class File(h5py.File):
         world_size_cm : [int, int] , optional
             side lengths [x, y] of the world in cm.
             rectangular world shape is assumed.
-            TODO: Cuboid world is also possible in track format
+            TODO: cuboid world is sepcified in track format 1.0, but not
+            supported by `File` yet
         strict_validate : bool, default=False
             if the file should be strictly validated against the track
-            format specification, when loaded from a path.
-            TODO: Should this validate against the version sepcified in
-            format_version or just against the most recent version?
+            format specification specified in `format_version`, when 
+            loaded from a path.
         format_version : [int, int], default=[1,0]
             version [major, minor] of track format specification
         format_url : str, default="https://git.imp.fu-berlin.de/bioroboticslab/robofish/track_format/-/releases/1.0"
             location of track format specification.
             should fit `format_version`.
         sampling_name : str, optional
-            How to specify your sampling:
+            text description of sampling. Details: See below
+        frequency_hz: int, optional
+            frequency of sampling. Details: See below
+        monotonic_time_points_us: Iterable of int, optional
+            time points of each sample in microseconds. Details: See below
+        calendar_time_points: Iterable of str, optional
+            time points of each sample in ISO 8601. Details: See below
+            
+        Attributes
+        ----------
+
         
-            1. (optional)
-                provide text description of your sampling in `sampling_name`
+        How to specify your sampling:
+        ----------
         
-            2.a (mandatory, if you have a constant sampling frequency)
-                specify `frequency_hz` with your sampling frequency in Hz
+        TODO: Move this into a Tutorial. Also Adjust Parameter descirpitons
+        for sampling_name, frequency_hz, monotonic_time_points_us and
+        calendar_time_points after that is done
 
-            2.b (mandatory, if you do NOT have a constant sampling frequency)
+        1. (optional) provide text description of your sampling in `sampling_name`
+        2. (mandatory) do one of two things: if you have a constant
+                sampling frequency, specify `frequency_hz` with your
+                sampling frequency in Hz.
+                If you do NOT have a constant sampling frequency
                 specify `monotonic_time_points_us` with a list[1] of time
                 points in microseconds on a montonic clock, one for each
                 sample in your dataset.
-
-            3.  (optional)
-                specify `calendar_time_points` with a list[2] of time points
+        3. (optional) specify `calendar_time_points` with a list[2] of time points
             in the ISO 8601 extended format with microsecond precision
             and time zone designator[3],  one for each sample in your
             dataset.
@@ -113,13 +126,6 @@ class File(h5py.File):
             [1] any Iterable of int
             [2] any Iterable of str
             [3] example:  "2020-11-18T13:21:34.117015+01:00"
-
-        frequency_hz: int, optional
-            refer to explanation of `sampling_name`
-        monotonic_time_points_us: Iterable of int, optional
-            refer to explanation of `sampling_name`
-        calendar_time_points: Iterable of str, optional
-            refer to explanation of `sampling_name`
         """
 
         if path is None: