add docstring for create_entity

src/robofish/io/file.py

@@ -316,16 +316,44 @@ class File(h5py.File):
         outlines: Iterable = None,
         sampling: str = None,
     ) -> str:
-        """Creates a new single entity.
+        """Adds a single entity
         
-        Args:
+        Adds a single entity as an hdf5 subgroup to self["entities"]
+        You can access the new entity via self["entities"][name]
+        
+        
+        Parameters
+        ----------
+        category: str
+            the category of the entity. The canonical values are 
+            ['fish', 'robot', 'obstacle'].
+        poses: Iterable, optional
+            position and orientation of the entity in the world over time
+            an array of shape (n_timesteps, 4) or (n_timesteps, 3)
+            the values in the last dimension represent
+            [pos_x, pos_y, ori_x_norm, ori_y_norm] or
+            [pos_x, pos_y, ori_radians]
+        name: str, optional 
+            name of the entity. If no name is given, a name is generated from
+            the category plus and id, e.g. 'fish_1'
+        positions: Iterable, optional
+            position of the entity in the world over time
+            an array of the shape (timesteps, 2)
+            the values in the last dimension represent [pos_x, pos_y]
+        orientations: Iterable, optional
+            orientation of the entity in the world over time
+            an array of shape (n_timesteps, 2) or (n_timesteps, 1)
+            the values in the last dimension represent
+            [ori_x_norm, ori_y_norm] or [ori_radians]
+        outlines: Iterable, optional
+            outline of the entity over time as simple polygonal chain
+            a 3-dimensional array. Exact shape is TODO
+        sampling: str, optional
             TODO
-            category: the  of the entity. The canonical values are ['fish', 'robot', 'obstacle'].
-            poses: optional two dimensional array, containing the poses of the entity (x,y,orientation_x, orientation_y).
-            poses_rad: optional two dimensional containing the poses of the entity (x,y, orientation_rad).
-            name: optional name of the entity. If no name is given, the  is used with an id (e.g. 'fish_1')
-            outlines: optional three dimensional array, containing the outlines of the entity
-        Returns:
+        
+        Returns
+        -------
+        entity: 
             Name of the created entity
         """