Skip to content

Commit

Permalink
Fill out longform documentation for new rclpy functions
Browse files Browse the repository at this point in the history
  • Loading branch information
Emerson Knapp committed Apr 16, 2019
1 parent 0a89248 commit b6f4478
Showing 1 changed file with 30 additions and 14 deletions.
44 changes: 30 additions & 14 deletions rclpy/src/rclpy/_rclpy.c
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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;
}
Expand Down Expand Up @@ -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)
Expand All @@ -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;
Expand All @@ -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;
}
Expand All @@ -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;
}
Expand Down

0 comments on commit b6f4478

Please sign in to comment.