Merge pull request #989 from tue-robotics/docstyle-fixes1

Fix documentation style

challenge_cleanup/src/challenge_cleanup/clean_inspect.py

@@ -10,6 +10,7 @@ class CleanInspect(smach.StateMachine):
     def __init__(self, robot, location_des):
         """
         Visit all selected locations from the list, and handle the found objects
+
         :param location_des is a designator resolving to a dictionary with fields ... TODO
         """
 

challenge_cleanup/src/challenge_cleanup/cleanup.py

@@ -78,6 +78,7 @@ class RoomToCleanUpLocations(smach.State):
     def __init__(self, knowledge, room_des, cleanup_locations):
         """
         Determine cleaning locations on runtime
+
         :param knowledge: challenge knowledge
         :param room_des: Designator resolving to room
         :type room_des: Designator(str)

challenge_dishwasher/src/challenge_dishwasher/open_dishwasher.py

@@ -22,6 +22,7 @@ def _clamp(abs_value, value):
 def _get_yaw_from_quaternion_msg(msg):
     """
     Returns the yaw angle from a rotation in quaternion representation (msg)
+
     :param msg: The quaternion msg
     :return: Yaw angle
     """
@@ -33,6 +34,7 @@ def _get_yaw_from_quaternion_msg(msg):
 def _wrap_angle_pi(angle):
     """
     Wraps between -pi and +pi
+
     :param angle: Input angle
     :return: Wrapped angle
     """

challenge_final/src/challenge_final/display_orders_on_map.py

@@ -17,6 +17,7 @@
 def color_map(N=256, normalized=False):
     """
     Generate an RGB color map of N different colors
+
     :param N : int amount of colors to generate
     :param normalized: bool indicating range of each channel: float32 in [0, 1] or int in [0, 255]
     :return a numpy.array of shape (N, 3) with a row for each color and each row is [R,G,B]

challenge_final/src/challenge_final/find_people.py

@@ -32,6 +32,7 @@
 def color_map(N=256, normalized=False):
     """
     Generate an RGB color map of N different colors
+
     :param N : int amount of colors to generate
     :param normalized: bool indicating range of each channel: float32 in [0, 1] or int in [0, 255]
     :return a numpy.array of shape (N, 3) with a row for each color and each row is [R,G,B]

challenge_final/src/challenge_final/get_orders.py

@@ -83,6 +83,7 @@ def iterate_next_person(user_data):
             def assign_random_drinks(user_data):
                 """
                 Edits user_data['detected_people'] elements (which are dicts) and adds a new 'selection'-key
+
                 :param user_data:
                 :return:
                 """
@@ -111,6 +112,7 @@ def assign_random_drinks(user_data):
             def store_current_person_order(user_data):
                 """
                 Edits user_data['detected_people'] elements (which are dicts) and adds a new 'selection'-key
+
                 :param user_data:
                 :return:
                 """
@@ -134,7 +136,8 @@ def store_current_person_order(user_data):
             @smach.cb_interface(outcomes=["done"])
             def increase_ppl_counter(user_data):
                 """
-                Edits user_data['detected_people'] elements (which are dicts) and adds a new 'selection'-key
+                Increments number of detected people.
+
                 :param user_data:
                 :return:
                 """

challenge_find_my_mates/src/challenge_find_my_mates/locate_people.py

@@ -31,6 +31,7 @@
 def color_map(N=256, normalized=False):
     """
     Generate an RGB color map of N different colors
+
     :param N : int amount of colors to generate
     :param normalized: bool indicating range of each channel: float32 in [0, 1] or int in [0, 255]
     :return a numpy.array of shape (N, 3) with a row for each color and each row is [R,G,B]

challenge_manipulation/src/empty_shelf_designator.py

@@ -27,6 +27,7 @@ class EmptyShelfDesignator(Designator):
     def __init__(self, robot, place_location_designator, name=None, area=None):
         """
         Designate an empty spot (as PoseStamped) on some designated entity
+
         :param robot: Robot whose worldmodel to use
         :param place_location_designator: Designator resolving to an Entity, e.g. EntityByIdDesignator
         :param name: name for introspection purposes
@@ -124,7 +125,9 @@ def create_selection_marker(self, selected_pose):
         return marker
 
     def determine_points_of_interest_with_area(self, e, area):
-        """ Determines the points of interest using an area
+        """
+        Determines the points of interest using an area
+
         :param e:
         :param area:
         :return:

challenge_manipulation/src/manipulation.py

@@ -132,7 +132,9 @@ def _resolve(self):
 class ForceDrive(smach.State):
     """ Force drives... """
     def __init__(self, robot, vx, vy, vth, duration):
-        """ Constructor
+        """
+        Constructor
+
         :param robot: robot object
         :param vx: velocity in x-direction
         :param vy: velocity in y-direction
@@ -158,7 +160,9 @@ class ForceRotate(smach.State):
     """ Force forth and back. If a timeout is exceeded, we won't do this anymore """
 
     def __init__(self, robot, vth, duration, timeout):
-        """ Constructor
+        """
+        Constructor
+
         :param robot: robot object
         :param vth: yaw-velocity
         :param duration: float indicating how long to drive
@@ -195,7 +199,9 @@ class FitEntity(smach.State):
     """ Fits an entity """
 
     def __init__(self, robot, entity_str):
-        """ Constructor
+        """
+        Constructor
+
         :param robot: robot object
         :param entity_str: string with the entity type to fit
         """
@@ -417,7 +423,9 @@ def __init__(self, robot, manipulated_items):
         not_manipulated = lambda entity: not entity in self.manipulated_items.resolve()
 
         def entity_z_pos(entity):
-            """ Checks if the entity is between the minimum and maximum grasp height
+            """
+            Checks if the entity is between the minimum and maximum grasp height
+
             :param entity:
             :return:
             """

challenge_restaurant/src/challenge_restaurant/store_waypoint.py

@@ -227,6 +227,7 @@ def execute(self, userdata=None):
     def _visualize_location(self, base_pose, location):
         """
         Visualize a marker on the base_pose with the text 'location' and rotated to the correct side.
+
         :param base_pose: kdl Frame (in map) where the waypoint is located
         :param location: The name of the location as a label
         :return:

challenge_set_a_table/src/challenge_set_a_table_states/clear_manipulate_machine.py

@@ -27,7 +27,9 @@ class ClearManipulateMachine(smach.StateMachine):
     - Place item
     """
     def __init__(self, robot, grasp_furniture_id, place_furniture_id1, place_furniture_id2):
-        """ Constructor
+        """
+        Constructor
+
         :param robot: robot object
         :param grasp_furniture_id: string identifying the furniture object where to grasp the objects
         :param place_furniture_id1: string identifying the furniture object where to place objects 1 and 2

challenge_set_a_table/src/challenge_set_a_table_states/manipulate_machine.py

@@ -65,11 +65,12 @@ def resolve(self):
 class GrabSingleItem(smach.StateMachine):
     """ Lock an object, announce it and grab it """
     def __init__(self, robot, grab_designator=None):
-        """ Constructor
+        """
+        Constructor
 
         :param robot: robot object
         :param grab_designator: EdEntityDesignator designating the item to grab. If not provided, a default one is
-        constructed (grabs the closest object in the volume of the surface)
+            constructed (grabs the closest object in the volume of the surface)
         """
         smach.StateMachine.__init__(self, outcomes=["succeeded", "failed"])
 

challenge_storing_groceries/src/challenge_storing_groceries/empty_shelf_designator.py

@@ -5,9 +5,9 @@
 
 
 class EmptyShelfDesignator(Designator):
-    """Designates an empty spot on the empty placement-shelve.
-    It does this by querying ED for entities that occupy some space.
-        If the result is no entities, then we found an open spot.
+    """
+    Designates an empty spot on the empty placement-shelve.
+    It does this by querying ED for entities that occupy some space. If the result is no entities, then we found an open spot.
 
     To test this in the robotics_test_lab with amigo-console:
     robot = amigo
@@ -19,6 +19,7 @@ class EmptyShelfDesignator(Designator):
     def __init__(self, robot, place_location_designator, name=None, area=None):
         """
         Designate an empty spot (as PoseStamped) on some designated entity
+
         :param robot: Robot whose worldmodel to use
         :param place_location_designator: Designator resolving to an Entity, e.g. EntityByIdDesignator
         :param name: name for introspection purposes
@@ -96,7 +97,9 @@ def create_selection_marker(self, selected_pose):
         return marker
 
     def determine_points_of_interest_with_area(self, e, area):
-        """ Determines the points of interest using an area
+        """
+        Determines the points of interest using an area
+
         :param e:
         :param area:
         :return:

challenge_storing_groceries/src/challenge_storing_groceries/fit_entity.py

@@ -7,7 +7,9 @@ class FitEntity(smach.State):
     """ Fits an entity """
 
     def __init__(self, robot, entity_str):
-        """ Constructor
+        """
+        Constructor
+
         :param robot: robot object
         :param entity_str: string with the entity type to fit
         """

challenge_storing_groceries/src/challenge_storing_groceries/force_base.py

@@ -4,7 +4,9 @@
 class ForceDrive(smach.State):
     """ Force drives... """
     def __init__(self, robot, vx, vy, vth, duration):
-        """ Constructor
+        """
+        Constructor
+
         :param robot: robot object
         :param vx: velocity in x-direction
         :param vy: velocity in y-direction
@@ -29,13 +31,13 @@ class ForceRotate(smach.State):
     """ Force forth and back. If a timeout is exceeded, we won't do this anymore """
 
     def __init__(self, robot, vth, duration, timeout):
-        """ Constructor
+        """
+        Constructor
+
         :param robot: robot object
         :param vth: yaw-velocity
         :param duration: float indicating how long to drive
         :param timeout: after this, timedout is returned
-        :return done: rotated back and forth
-        :return timedout: this takes too long
         """
         smach.State.__init__(self, outcomes=['done', 'timedout'])
         self._robot = robot
@@ -45,7 +47,12 @@ def __init__(self, robot, vth, duration, timeout):
         self._first_stamp = None
 
     def execute(self, userdata=None):
-        """ Executes the state """
+        """
+        Executes the state
+
+        :param userdata:
+        :return: "done" if rotated back and forth, or "timedout" if this takes too long
+        """
         if self._first_stamp is None:
             self._first_stamp = rospy.Time.now()
 

challenge_storing_groceries/src/challenge_storing_groceries/manipulate_machine.py

@@ -77,7 +77,7 @@ def __init__(self, robot, grab_designator=None):
 
         :param robot: robot object
         :param grab_designator: EdEntityDesignator designating the item to grab. If not provided, a default one is
-        constructed (grabs the closest object in the volume of the surface)
+            constructed (grabs the closest object in the volume of the surface)
         """
         smach.StateMachine.__init__(self, outcomes=["succeeded", "failed"])
 
@@ -186,7 +186,9 @@ class ManipulateMachine(smach.StateMachine):
     - Place item
     """
     def __init__(self, robot, grab_designator_1=None, grab_designator_2=None, place_designator=None, pdf_writer=None):
-        """ Constructor
+        """
+        Constructor
+
         :param robot: robot object
         :param grab_designator_1: EdEntityDesignator designating the item to grab
         :param grab_designator_2: EdEntityDesignator designating the item to grab

challenge_storing_groceries/src/challenge_storing_groceries/open_door.py

@@ -25,6 +25,7 @@
 def _clamp(abs_value, value):
     """
     Clamps the value to be between -abs_value and +abs_value
+
     :param abs_value: limit of the value in both positive and negative direction
     :param value: value to be clamped...
     :return: The -abs_value when value is smaller than -abs_value OR +abs_value when value is more than +abs_value
@@ -35,6 +36,7 @@ def _clamp(abs_value, value):
 def _get_yaw_from_quaternion_msg(msg):
     """
     Returns the yaw angle from a rotation in quaternion representation (msg)
+
     :param msg: The quaternion msg
     :return: Yaw angle
     """
@@ -47,6 +49,7 @@ def _wrap_angle_pi(angle):
     """
     Wraps between -pi and +pi
     -pi is excluded, (-pi, pi]
+
     :param angle: Input angle
     :return: Wrapped angle
     """

challenge_storing_groceries/src/challenge_storing_groceries/pdf.py

@@ -92,7 +92,9 @@ def execute(self, userdata=None):
         return "done"
 
     def set_designator(self, designator):
-        """ Sets a designator that can be used to add to the internal list.
+        """
+        Sets a designator that can be used to add to the internal list.
+
         :param designator: designator with list of ClassificationResults as resolve type
         """
         self._designator = designator

challenge_take_out_the_garbage/src/challenge_take_out_the_garbage/pick_up.py

@@ -200,6 +200,7 @@ def __init__(self, robot, arm_designator, grabbed_entity_label="", grabbed_entit
                  arm_configuration="handover_to_human"):
         """
         Hold up hand to accept an object and close hand once something is inserted
+
         :param robot: Robot with which to execute this behavior
         :param arm_designator: ArmDesignator resolving to arm accept item into
         :param grabbed_entity_label: What ID to give a dummy item in case no grabbed_entity_designator is supplied

challenge_where_is_this/src/challenge_where_is_this/inform_machine.py

@@ -37,11 +37,12 @@ class WaitMode(enum.Enum):
 
 
 class EntityFromHmiResults(ds.Designator):
-    """ Designator to pick the closest item on top of the table to grab. This is used for testing
-
+    """
+    Designator to pick the closest item on top of the table to grab. This is used for testing
     """
     def __init__(self, robot, hmi_result_des, parse=True):
-        """ Constructor
+        """
+        Constructor
 
         :param robot: robot object
         :param hmi_result_des:
@@ -53,7 +54,8 @@ def __init__(self, robot, hmi_result_des, parse=True):
         self.parse = parse
 
     def _resolve(self):
-        """ Resolves
+        """
+        Resolves
 
         :return: entity in the <area_description> of the <surface_designator> that is closest to the robot
         """
@@ -70,7 +72,9 @@ def _resolve(self):
 
 class GuideToRoomOrObject(smach.StateMachine):
     def __init__(self, robot, entity_des, operator_distance=1.5, operator_radius=0.5):
-        """ Constructor
+        """
+        Constructor
+
         :param robot: robot object
         :param entity_des: designator resolving to a room or a piece of furniture
         :param operator_distance: (float) check for the operator to be within this range of the robot
@@ -171,7 +175,9 @@ def determine_type(userdata=None):
 
 class InformMachine(smach.StateMachine):
     def __init__(self, robot):
-        """ Constructor
+        """
+        Constructor
+
         :param robot: robot object
         """
         smach.StateMachine.__init__(self, outcomes=["succeeded", "failed"])

challenge_where_is_this/src/challenge_where_is_this/simulation.py

@@ -12,6 +12,7 @@
 def _toggle_operator(_):
     """
     Toggles if the operator is following
+
     :param _:
     :return:
     """
@@ -24,6 +25,7 @@ def _toggle_operator(_):
 def mock_detect_operator(robot, distance=1.0, radius=0.5):  # noinspection
     """
     Mocks the 'detect operator' method. Only returns if the mocked operator is available
+
     :param robot: -
     :param distance: -
     :param radius: -

robot_smach_states/examples/navigation/example_guidance.py

@@ -13,6 +13,7 @@
 def toggle_operator(_):
     """
     Toggles if the operator is following
+
     :param _:
     :return:
     """