From 29bfb56fc71826eb1a3ad86d8283319c2b294b07 Mon Sep 17 00:00:00 2001
From: Théo de la Hogue
Date: Mon, 11 Mar 2024 09:10:30 +0100
Subject: Improving annotations.

---
 src/argaze/GazeFeatures.py | 27 ++++++++++++++++-----------
 1 file changed, 16 insertions(+), 11 deletions(-)

(limited to 'src')

diff --git a/src/argaze/GazeFeatures.py b/src/argaze/GazeFeatures.py
index 263f793..fea1331 100644
--- a/src/argaze/GazeFeatures.py
+++ b/src/argaze/GazeFeatures.py
@@ -504,6 +504,9 @@ def is_fixation(gaze_movement):
 
     return type(gaze_movement).__bases__[0] == Fixation or type(gaze_movement) == Fixation
 
+SaccadeType = TypeVar('Saccade', bound="Saccade")
+# Type definition for type annotation convenience
+
 class Saccade(GazeMovement):
     """Define abstract saccade as gaze movement."""
 
@@ -570,36 +573,38 @@ class GazeMovementIdentifier(DataFeatures.PipelineStepObject):
         super().__init__()
 
     @DataFeatures.PipelineStepMethod
-    def identify(self, timestamp: int|float, gaze_position: GazePosition, terminate:bool=False) -> Tuple[GazeMovementType, GazeMovementType]:
-        """Identify gaze movement from successive timestamped gaze positions. 
-        Each identified gaze movement should share its first/last gaze position with previous/next gaze movement.
+    def identify(self, timestamp: int|float, gaze_position: GazePosition, terminate:bool=False) -> GazeMovementType:
+        """Identify gaze movement from successive timestamped gaze positions.
+
+        !!! warning "Mandatory"
+            Each identified gaze movement have to share its first/last gaze position with previous/next gaze movement.
 
         Parameters:
-            timestamp:
-            gaze_position:
+            timestamp: gaze position timestamp
+            gaze_position: new gaze position from where identification have to be done considering former gaze positions.
             terminate: allows to notify identification algorithm that given gaze position will be the last one.
         
         Returns:
-            gaze_movement: identified gaze movement once it is finished otherwise it returns empty gaze movement.
+            gaze_movement: identified gaze movement once it is finished otherwise it returns empty gaze movement at least.
         """
 
         raise NotImplementedError('identify() method not implemented')
 
     @property
     def current_gaze_movement(self) -> GazeMovementType:
-        """Get currently identified gaze movement."""
+        """Get the current identified gaze movement (finished or in progress) if it exists otherwise, an empty gaze movement."""
 
         raise NotImplementedError('current_gaze_movement getter not implemented')
 
     @property
-    def current_fixation(self) -> GazeMovementType:
-        """Get currently identified fixation."""
+    def current_fixation(self) -> FixationType:
+        """Get the current identified fixation (finished or in progress) if it exists otherwise, an empty gaze movement."""
 
         raise NotImplementedError('current_fixation getter not implemented')
 
     @property
-    def current_saccade(self) -> GazeMovementType:
-        """Get currently identified saccade."""
+    def current_saccade(self) -> SaccadeType:
+        """Get the current identified saccade (finished or in progress) if it exists otherwise, an empty gaze movement."""
 
         raise NotImplementedError('current_saccade getter not implemented')
 
-- 
cgit v1.1