Fill out longform documentation for new rclpy functions

rclpy/src/rclpy/_rclpy.c

@@ -1349,9 +1349,17 @@ _rclpy_destroy_event(PyObject * pycapsule)
 
 /// Create an event object for QoS event handling.
 /**
-  * TODO(eknapp) rclpy_create_event longdoc
-  * \param[in] pyevent_type
-  * \param[in] pyparent
+  * This function will create an event handle for the given Subscription or Publisher parent.
+  *
+  * Raises MemoryError if the event can't be allocated
+  * Raises RuntimeError on initialization failure
+  * Raises TypeError if the capsules are not the correct types
+  *
+  * \param[in] pyevent_type Enum value of
+  *   rcl_publisher_event_type_t or rcl_subscription_event_type_t, chosen by the type of pyparent
+  * \param[in] pyparent Capsule containing the parent Publisher or Subscription
+  * \return capsule containing rcl_event_t
+  * \return NULL on failure
   */
 static PyObject *
 rclpy_create_event(PyObject * Py_UNUSED(self), PyObject * args)
@@ -1379,7 +1387,7 @@ rclpy_create_event(PyObject * Py_UNUSED(self), PyObject * args)
       return NULL;
     }
   } else {
-    PyErr_Format(PyExc_RuntimeError, "Event parent was not a valid Publisher or Subscription.");
+    PyErr_Format(PyExc_TypeError, "Event parent was not a valid Publisher or Subscription.");
     rcl_reset_error();
     return NULL;
   }
@@ -3171,12 +3179,20 @@ rclpy_take_response(PyObject * Py_UNUSED(self), PyObject * args)
   return pytuple;
 }
 
-/// Take a QoS event for a given publisher or subscription.
+/// Get a pending QoS event's data
 /**
-  * TODO(eknapp) rclpy_take_event longdoc
-  * \param[in] pyevent
-  * \param[in] pyparent
-  * \param[in] pyevent_type
+  * After having determined that a middleware event is ready, get the callback payload.
+  *
+  * Raises RuntimeError on failure to take the event from the middleware
+  * Raises TypeError if the capsules are not the correct types
+  * Raises ValueError on unknown event_type argument
+  *
+  * \param[in] pyevent Event handle from rclpy_create_event
+  * \param[in] pyevent_type Enum value of
+  *   rcl_publisher_event_type_t or rcl_subscription_event_type_t, chosen by the type of pyparent
+  * \param[in] pyparent Capsule containing the parent Publisher or Subscription
+  * \return Python object from rclpy.qos_event containing callback data
+  * \return NULL on failure
   */
 static PyObject *
 rclpy_take_event(PyObject * Py_UNUSED(self), PyObject * args)
@@ -3202,7 +3218,7 @@ rclpy_take_event(PyObject * Py_UNUSED(self), PyObject * args)
   } else if (PyCapsule_IsValid(pyparent, "rcl_publisher_t")) {
     is_subscription = false;
   } else {
-    PyErr_Format(PyExc_RuntimeError,
+    PyErr_Format(PyExc_TypeError,
       "Parent handle was not a valid Publisher or Subscription.");
     rcl_reset_error();
     return NULL;
@@ -3217,8 +3233,8 @@ rclpy_take_event(PyObject * Py_UNUSED(self), PyObject * args)
         callback_info = PyMem_Malloc(sizeof(rmw_liveliness_changed_status_t));
         break;
       default:
-        PyErr_Format(PyExc_RuntimeError,
-          "Event type %d not supported by rclpy.", pyevent_type);
+        PyErr_Format(PyExc_ValueError,
+          "Event type %d for Subscriptions not understood by rclpy.", pyevent_type);
         rcl_reset_error();
         return NULL;
     }
@@ -3231,8 +3247,8 @@ rclpy_take_event(PyObject * Py_UNUSED(self), PyObject * args)
         callback_info = PyMem_Malloc(sizeof(rmw_liveliness_lost_status_t));
         break;
       default:
-        PyErr_Format(PyExc_RuntimeError,
-          "Event type %d not supported by rclpy.", pyevent_type);
+        PyErr_Format(PyExc_ValueError,
+          "Event type %d for Publishers not understood by rclpy.", pyevent_type);
         rcl_reset_error();
         return NULL;
     }