doc(examples): Add docstrings to the example script functions

Added docstrings to all the remaining example scripts.

Author: Pilar-TG0

examples/01_Retrieving_Data/right_index_events_based.py

@@ -15,6 +15,9 @@
 
 
 def process_right_index():
+    """
+    Retrieve the pressure data for the right index finger from the etee driver. Print the values.
+    """
     right_index_pull = etee.get_index_pull('right')
     right_index_force = etee.get_index_force('right')
     current_time = datetime.now().strftime("%H:%M:%S.%f")

examples/01_Retrieving_Data/right_index_getter_function.py

@@ -16,6 +16,12 @@
 
 
 def process_right_index():
+    """
+    Retrieve the pressure data for the right index finger from the etee driver.
+
+    :return: Index finger pull pressure and force pressure, from the right eteeController.
+    :rtype: int, int
+    """
     right_index_pull = etee.get_index_pull('right')
     right_index_force = etee.get_index_force('right')
     return right_index_pull, right_index_force

examples/02_Print_Data/print_etee_euler_angles.py

@@ -16,6 +16,9 @@
 
 
 def print_title():
+    """
+    Print CLI graphics for the application title.
+    """
     print("======================================================")
     print(r"        __               ___    ____  ____")
     print(r"  ___  / /____  ___     /   |  / __ \/  _/")

examples/02_Print_Data/print_etee_finger_data.py

@@ -13,6 +13,15 @@
 
 
 def process_finger(dev, finger):
+    """
+    Retrieve the selected device's finger values from the etee driver.
+
+    :param str dev: Selected device hand. Possible values: "left", "right".
+    :param str finger: Selected finger. Possible values: "thumb", "index", "middle", "ring", "pinky".
+    :return: Array containing the selected controller's index finger values: pull pressure, force pressure,
+    touch and click.
+    :rtype: list[Any]
+    """
     finger_pull = finger + "_pull"
     finger_force = finger + "_force"
     finger_touch = finger + "_touched"
@@ -24,6 +33,9 @@ def process_finger(dev, finger):
 
 
 def print_title():
+    """
+    Print CLI graphics for the application title.
+    """
     print("======================================================")
     print(r"        __               ___    ____  ____")
     print(r"  ___  / /____  ___     /   |  / __ \/  _/")

examples/02_Print_Data/print_etee_fingers_all_data.py

@@ -14,6 +14,9 @@
 
 
 def print_title():
+    """
+    Print CLI graphics for the application title.
+    """
     print("======================================================")
     print(r"        __               ___    ____  ____")
     print(r"  ___  / /____  ___     /   |  / __ \/  _/")

examples/02_Print_Data/print_etee_imu.py

@@ -13,6 +13,9 @@
 
 
 def print_title():
+    """
+    Print CLI graphics for the application title.
+    """
     print("======================================================")
     print(r"        __               ___    ____  ____")
     print(r"  ___  / /____  ___     /   |  / __ \/  _/")
@@ -25,6 +28,14 @@ def print_title():
 
 
 def adjust_imu(original_arr, offsets_arr):
+    """
+    Apply offsets to the original array.
+
+    :param list[int] original_arr: Original IMU (i.e. accel, gyro or mag) XYZ array without offsets.
+    :param list[int] offsets_arr: Array of XYZ offsets to be applied to the original array.
+    :return: Adjusted IMU array after applying offsets.
+    :rtype: list[int]
+    """
     adj_arr = [0, 0, 0]
     if original_arr is None or offsets_arr is None:
         pass

examples/02_Print_Data/print_etee_quaternions.py

@@ -14,6 +14,9 @@
 
 
 def print_title():
+    """
+    Print CLI graphics for the application title.
+    """
     print("======================================================")
     print(r"        __               ___    ____  ____")
     print(r"  ___  / /____  ___     /   |  / __ \/  _/")

examples/02_Print_Data/print_etee_slider_data.py

@@ -13,13 +13,23 @@
 
 
 def process_slider(dev):
+    """
+    Retrieve the selected device's slider values from the etee driver.
+
+    :param str dev: Selected device hand. Possible values: "left", "right".
+    :return: Array containing the selected controller's slider values: Y-axis position, touch, up and down button values.
+    :rtype: list[Any]
+    """
     slider = [etee.get_slider_value(dev),
               etee.get_slider_touched(dev),
               etee.get_slider_up_button(dev), etee.get_slider_down_button(dev)]
     return slider
 
 
 def print_title():
+    """
+    Print CLI graphics for the application title.
+    """
     print("======================================================")
     print(r"        __               ___    ____  ____")
     print(r"  ___  / /____  ___     /   |  / __ \/  _/")

examples/02_Print_Data/print_etee_sliders_buttons.py

@@ -13,16 +13,31 @@
 
 
 def process_left_slider_buttons():
+    """
+    Retrieve the left slider button values from the etee driver.
+
+    :return: Array containing the left controller's slider button values: up and down button states.
+    :rtype: list[bool]
+    """
     left_slider = [etee.get_slider_up_button('left'), etee.get_slider_down_button('left')]
     return left_slider
 
 
 def process_right_slider_buttons():
+    """
+    Retrieve the right slider button values from the etee driver.
+
+    :return: Array containing the right controller's slider button values: up and down button states.
+    :rtype: list[bool]
+    """
     right_slider = [etee.get_slider_up_button('right'), etee.get_slider_down_button('right')]
     return right_slider
 
 
 def print_title():
+    """
+    Print CLI graphics for the application title.
+    """
     print("======================================================")
     print(r"        __               ___    ____  ____")
     print(r"  ___  / /____  ___     /   |  / __ \/  _/")
@@ -35,6 +50,14 @@ def print_title():
 
 
 def check_controller_connection(left_data, right_data):
+    """
+    Check that both controllers are connected. If not, attempt re-connection.
+
+    :param str left_data: Left controller button values from the etee driver. If a controller disconnects, the values in the buffer will reset to None.
+    :param str right_data: Right controller button values from the etee driver. If a controller disconnects, the values in the buffer will reset to None.
+    :return: True if both controllers are still connected; False if otherwise
+    :rtype: bool
+    """
     connection = True
     if left_data[0] == None and right_data[0] == None:
         print("---")
@@ -56,6 +79,7 @@ def check_controller_connection(left_data, right_data):
         connection = False
     return connection
 
+
 if __name__ == "__main__":
     # Initialise the etee driver and find dongle
     etee = EteeController()

examples/02_Print_Data/print_etee_trackpad_data.py

@@ -13,13 +13,24 @@
 
 
 def process_trackpad(dev):
+    """
+    Retrieve the selected device's trackpad values from the etee driver.
+
+    :param str dev: Selected device hand. Possible values: "left", "right".
+    :return: Two arrays containing the selected controller's trackpad values. One containing the location
+    (X-axis position, Y-axis position), and another the pressure (pull pressure, force pressure, touch and click).
+    :rtype: list[int], list[Any]
+    """
     loc = [etee.get_data(dev, "trackpad_x"), etee.get_data(dev, "trackpad_y")]
     pressure = [etee.get_data(dev, "trackpad_pull"), etee.get_data(dev, "trackpad_force"),
                 etee.get_data(dev, "trackpad_touched"), etee.get_data(dev, "trackpad_clicked")]
     return loc, pressure
 
 
 def print_title():
+    """
+    Print CLI graphics for the application title.
+    """
     print("======================================================")
     print(r"        __               ___    ____  ____")
     print(r"  ___  / /____  ___     /   |  / __ \/  _/")