update file.py docstring

src/robofish/io/file.py

@@ -30,6 +30,7 @@ import uuid
 import deprecation
 import types
 
+# Remember: Update docstring when updating these two global variables
 default_format_version = np.array([1, 0], dtype=np.int32)
 
 default_format_url = (
@@ -61,26 +62,64 @@ class File(h5py.File):
     ):
         """Create a new RoboFish Track Format object.
 
-        When called with a path, it is loaded, otherwise a new temporary file is created.
+        When called with a path, it is loaded, otherwise a new temporary
+        file is created. File contents can be validated against the
+        track format specification.
 
         Parameters
         ----------
         path : str or Path, optional
             Location of file to be opened. If not provided, mode is ignored.
-
-        mode : str
-            r        Readonly, file must exist (default)
-            r+       Read/write, file must exist
-            w        Create file, truncate if exists
-            x        Create file, fail if exists
-            a        Read/write if exists, create otherwise
-
-        world_size_cm
-            optional integer array of the world size in cm
-        strict_validate
-            optional boolean, if the file should be strictly validated, when loaded from a path. The default is False.
-        format_version
-            optional version [major, minor] of the trackformat specification
+        mode : str, default='r'
+            'r'        Readonly, file must exist
+            'r+'       Read/write, file must exist
+            'w'        Create file, truncate if exists
+            'x'        Create file, fail if exists
+            'a'        Read/write if exists, create otherwise
+        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
+        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_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:
+
+            1. (optional)
+                provide text description of your sampling in `sampling_name`
+
+            2.a (mandatory, if you have a constant sampling frequency)
+                specify `frequency_hz` with your sampling frequency in Hz
+
+            2.b (mandatory, 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
+                in the ISO 8601 extended format with microsecond precision
+                and time zone designator[3],  one for each sample in your
+                dataset.
+
+            [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: