From b6f44782c8f390e41f2aea5048ca2f703cebb129 Mon Sep 17 00:00:00 2001 From: Emerson Knapp Date: Tue, 16 Apr 2019 13:14:16 -0700 Subject: [PATCH] Fill out longform documentation for new rclpy functions --- rclpy/src/rclpy/_rclpy.c | 44 +++++++++++++++++++++++++++------------- 1 file changed, 30 insertions(+), 14 deletions(-) diff --git a/rclpy/src/rclpy/_rclpy.c b/rclpy/src/rclpy/_rclpy.c index e854b43d1..77aeb719b 100644 --- a/rclpy/src/rclpy/_rclpy.c +++ b/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; }