Better docstring incl. types, explain units ++

ispyb/sp/xtalimaging.py

@@ -58,14 +58,26 @@ def insert_subsample_for_image_full_path(
         position2x=None,
         position2y=None,
     ):
-        """Store new subsample for a given sample image.
+        """Store new subsample for a given sample image. Either specify a point
+        (by providing position1x and position1y) or a ROI box (by additionally
+        providing position2x and position2y). Position coordinates are given in
+        pixels from the top-left corner of the image.
 
         :param image_full_path: The full path to the sample image
+        :type image_full_path: str
         :param source: manual or auto
-        :param position1x: x component of position, or if position2x,y given, then x component of top left corner of ROI box
-        :param position1y: y component of position, or if position2x,y given, then y component of top left corner of ROI box
-        :param position2x: x component of lower right corner of ROI box
-        :param position2y: y component of lower right corner of ROI box
+        :type source: str
+        :param position1x: x component of position1
+        :type position1x: int
+        :param position1y: y component of position1
+        :type position1y: int
+        :param position2x: x component of position2 which is the lower right
+        corner of a ROI box
+        :type position2x: int
+        :param position2y: y component of position2 which is the lower right
+        corner of a ROI box
+        :type position2y: int
+        :return: The subsample_id.
         """
         id = None
         return self.get_connection().call_sp_write(