Added comments to 11 items across 2 files

examples/hand_guide.py

@@ -20,42 +20,37 @@
 
 class HandGuideClient(fri.LBRClient):
     """
-    Initializes and manages a robotic arm's state, commanding its position based
-    on estimated joint states and external wrenches. It updates the robot's pose,
-    checks command mode, and filters wrench estimates to ensure smooth motion control.
+    Initializes a hand guide client for interacting with a robot arm. It estimates
+    joint states and wrenches, filters sensor data, and updates robot commands
+    based on the controller's output to maintain stable movement.
 
     Attributes:
-        controller (AdmittanceController|None): Initialized with an instance of
-            AdmittanceController in the constructor. It represents a controller
-            used for controlling the robot's joints based on estimated wrenches
-            and other factors.
-        joint_state_estimator (JointStateEstimator|None): Initialized with the
-            instance itself as its argument, indicating it's responsible for
-            estimating joint states based on current conditions.
+        controller (AdmittanceController|None): Initialized with lbr_ver as a
+            parameter in its constructor method, likely controlling the robot's admittance.
+        joint_state_estimator (JointStateEstimator): Initialized with a reference
+            to the current `HandGuideClient` instance as its argument. It estimates
+            joint states of the robot.
         external_torque_estimator (FRIExternalTorqueEstimator|None): Initialized
-            with its constructor being called on self, which suggests it estimates
-            external torques acting on the robot.
-        wrench_estimator (WrenchEstimatorTaskOffset|JointStateEstimator|FRIExternalTorqueEstimator):
-            Associated with a robot, ee link, and joint state estimator. It estimates
-            task-space forces and torques from joint sensor readings and external
-            torque estimations.
-        wrench_filter (ExponentialStateFilter): Used to filter wrench data from
-            the `WrenchEstimatorTaskOffset`. It appears to be a state estimation
-            method to provide more accurate results.
+            with a reference to the client object itself during construction.
+        wrench_estimator (WrenchEstimatorTaskOffset|None): Initialized with four
+            parameters: the instance itself, its associated joint state estimator,
+            external torque estimator, and controller. It filters and estimates
+            wrench values based on task offsets.
+        wrench_filter (ExponentialStateFilter): Used to filter the wrench estimates
+            from the WrenchEstimatorTaskOffset instance associated with it.
 
     """
     def __init__(self, lbr_ver):
         """
-        Initializes objects for admittance control, joint state estimation, external
-        torque estimation, wrench estimation, and exponential state filtering based
-        on provided parameters. It also establishes relationships between these
-        components for coordinated functioning.
+        Initializes various components necessary for the controller and estimators,
+        including an admittance controller, joint state estimator, external torque
+        estimator, wrench estimator, and wrench filter. These are likely used to
+        control a robot arm's movements.
 
         Args:
-            lbr_ver (str | int): Used to specify the version or identifier of the
-                robot. This value is passed to the AdmittanceController class
-                during initialization. It appears to be related to the robotic
-                arm's model.
+            lbr_ver (str | int | float): Used to specify a version or other version
+                information about the LBR (Lightweight Robot) being controlled by
+                this class instance.
 
         """
         super().__init__()
@@ -82,9 +77,10 @@ def onStateChange(self, old_state, new_state):
 
     def waitForCommand(self):
         """
-        Waits for a command from the client to be executed. It checks if the current
-        client mode matches POSITION, updates the wrench estimator, retrieves the
-        current joint position, and executes the command position.
+        Checks if the robot's client command mode is set to POSITION, otherwise
+        it prints an error message and exits. If the mode is correct, it retrieves
+        the current joint position from the robot state and calls the `command_position`
+        method.
 
         """
         if self.robotState().getClientCommandMode() != POSITION:
@@ -93,15 +89,14 @@ def waitForCommand(self):
             )
             raise SystemExit
 
-        self.wrench_estimator.update()
         self.q = self.robotState().getIpoJointPosition()
         self.command_position()
 
     def command(self):
         """
-        Updates robot position commands by filtering and processing wrench data
-        from the wrench estimator, then calls the `controller` function to compute
-        new joint positions. It also sets the joint position command of the robot.
+        Updates the robot's joint position based on estimated wrench and filtered
+        feedback, using a controller to compute the new position. It checks if the
+        estimator is ready before proceeding with the update process.
 
         """
         if not self.wrench_estimator.ready():
@@ -125,13 +120,14 @@ def command(self):
 
 def args_factory():
     """
-    Creates an instance of the ArgumentParser class and defines arguments for
-    parsing command-line input. It returns a Namespace object containing user-specified
-    values for hostname, port, and LBR Med version number.
+    Parses command-line arguments using argparse. It defines three arguments:
+    hostname, port, and lbr-ver, which are then returned as parsed arguments. The
+    lbr-ver argument requires a specific integer value from the list [7, 14] and
+    is mandatory.
 
     Returns:
-        argparseNamespace: An object containing arguments parsed from the command
-        line. This object holds attributes for `hostname`, `port`, and `lbr_ver`.
+        argparseNamespace: An instance that stores the parsed command-line arguments
+        as attributes, allowing access to them as a dictionary-like object.
 
     """
     parser = argparse.ArgumentParser(description="LRBJointSineOverlay example.")
@@ -162,13 +158,14 @@ def args_factory():
 
 def main():
     """
-    Initializes a connection to a KUKA Sunrise controller,  attempts to establish
-    communication, and repeatedly polls the robot's state until idle or an error
-    occurs. It also handles keyboard interrupts and system exits before disconnecting
-    from the controller and terminating.
+    Initializes a FRI client, connects to a KUKA Sunrise controller, and executes
+    a sequence of steps. It continuously checks if the robot session is idle; if
+    so, it breaks out of the loop. The function gracefully handles keyboard
+    interrupts and system exits.
 
     Returns:
-        int: 1 when connection to KUKA Sunrise controller fails, and 0 otherwise.
+        int|None: 1 when connection to KUKA Sunrise controller fails or 0 on
+        successful execution.
 
     """
     print("Running FRI Version:", fri.FRI_CLIENT_VERSION)

setup.py

@@ -11,10 +11,10 @@
 # Read the configuration settings
 class UserInputRequired(Exception):
     """
-    Defines a custom exception to handle situations where user input is missing
-    or incomplete. It inherits from Python's built-in `Exception` class and takes
-    an error message as an argument, allowing for customizable error handling and
-    messaging.
+    Defines a custom exception that signals the need for user input to proceed
+    with a particular operation or action. It serves as a signal to handle missing
+    or invalid user data, ensuring program flow continues after receiving required
+    input from users.
 
     """
     def __init__(self, msg):
@@ -41,30 +41,30 @@ def __init__(self, msg):
 # If you need multiple extensions, see scikit-build.
 class CMakeExtension(Extension):
     """
-    Initializes a C extension for use with Pybind11. It sets up the extension's
-    name and source directory, resolving the source directory to an absolute path
-    using Python's `os.fspath` and `Path.resolve` functions.
+    Initializes a CMake extension project with given name and source directory
+    path. It sets up the basic structure for a CMake build, allowing sources to
+    be added later. The `sourcedir` parameter is resolved to an absolute file
+    system path.
 
     Attributes:
-        sourcedir (Path|str): Resolved to a string path using
-            `os.fspath(Path(sourcedir).resolve())`. It represents the directory
-            where sources for the CMake extension are located.
+        sourcedir (osPathLike[str]|str): Set to a normalized path string. It stores
+            the source directory for the extension. This value can be obtained
+            from a Path object, which provides file system operations.
 
     """
     def __init__(self, name: str, sourcedir: str = "") -> None:
         """
-        Initializes an instance of the class with a name and optionally a sourcedir.
-        It calls the superclass's `__init__` method to set up basic attributes,
-        then sets the sourcedir attribute to its resolved absolute path.
+        Initializes an instance with a specified name and optionally a sourcedir
+        path. The `super().__init__` call creates a base Extension instance with
+        the given name, while also initializing a sources list. The sourcedir path
+        is resolved and stored in self.sourcedir.
 
         Args:
-            name (str): Required to be passed during object instantiation. It is
-                expected to be a string representing the name associated with the
-                instance being created.
-            sourcedir (str): Initialized with an empty string. It represents the
-                directory where source files are located. The `os.fspath` and
-                `Path.resolve()` functions are used to ensure the path is resolved
-                and converted to a string.
+            name (str): Required for initialization. It represents the name of an
+                object being created and will be used as its identifier.
+            sourcedir (str): Optional, as indicated by its default value. It
+                represents the source directory path that can be resolved to an
+                absolute path using os.fspath and Path.resolve.
 
         """
         super().__init__(name, sources=[])
@@ -73,20 +73,21 @@ def __init__(self, name: str, sourcedir: str = "") -> None:
 
 class CMakeBuild(build_ext):
     """
-    Extends the `build_ext` class to build C++ extensions using the CMake build
-    system, handling various configuration options and environmental variables for
-    cross-platform compatibility.
+    Extends the `build_ext` class from Python's `setuptools` package to provide
+    custom CMake-based build logic for extension modules. It generates and builds
+    CMake project files, incorporating environment variables and project-specific
+    settings.
 
     """
     def build_extension(self, ext: CMakeExtension) -> None:
         """
-        Configures and builds a CMake-based extension using Python's subprocess
-        module, invoking the cmake command to generate build files and then running
-        the build process according to the specified configuration.
+        Builds and configures a CMake-based extension using specified environment
+        variables, compiler types, and configuration settings to generate native
+        libraries for various platforms and architectures.
 
         Args:
-            ext (CMakeExtension): Required for the function to execute. It represents
-                an extension being built with CMake.
+            ext (CMakeExtension): Expected to be a specific extension that needs
+                to be built.
 
         """
         # Must be in this form due to bug in .resolve() only fixed in Python 3.10+
@@ -192,7 +193,7 @@ def build_extension(self, ext: CMakeExtension) -> None:
 
 setup(
     name="pyfri",
-    version="1.2.0",
+    version="1.2.1",
     author="Christopher E. Mower, Martin Huber",
     author_email="[email protected], [email protected]",
     description="Python bindings for the FRI Client SDK library.",