documentation: Cleanup and clarification
This change clarifies some of the built-in sd_event behavior and points
the reader to the relevant sd_event documentation where applicable.
Change-Id: Ic12d6a2d4364aa529240660a532af2bde4a4d89f
Signed-off-by: William A. Kennington III <wak@google.com>
diff --git a/src/sdeventplus/source/child.hpp b/src/sdeventplus/source/child.hpp
index c9ba79b..3a9857f 100644
--- a/src/sdeventplus/source/child.hpp
+++ b/src/sdeventplus/source/child.hpp
@@ -11,6 +11,7 @@
/** @class Child
* @brief A wrapper around the sd_event_source child type
+ * See sd_event_add_child(3) for more information
*/
class Child : public Base
{
@@ -18,7 +19,8 @@
using Callback = std::function<void(Child& source, const siginfo_t* si)>;
/** @brief Adds a new child source handler to the Event
- * Executes the callback upon the child events occurring
+ * This type of source defaults to Enabled::Oneshot, and needs to be
+ * reconfigured upon each callback.
*
* @param[in] event - The event to attach the handler
* @param[in] pid - The pid of the child to monitor
diff --git a/src/sdeventplus/source/event.hpp b/src/sdeventplus/source/event.hpp
index 9ab6be7..cc23209 100644
--- a/src/sdeventplus/source/event.hpp
+++ b/src/sdeventplus/source/event.hpp
@@ -10,6 +10,12 @@
namespace source
{
+/** @class EventBase
+ * @brief A wrapper around the sd_event_source defer type
+ * See sd_event_add_defer(3) for more information
+ * There are multiple types of defer sources, instantiate
+ * Defer, Post, or Exit depending on the required event.
+ */
class EventBase : public Base
{
public:
@@ -19,7 +25,8 @@
using CreateFunc = decltype(&internal::SdEvent::sd_event_add_exit);
/** @brief Adds a new event source handler to the Event
- * Executes the callback upon events occurring
+ * This type of source defaults to Enabled::Oneshot, and needs to be
+ * reconfigured upon each callback.
*
* @param[in] name - The name identifying the create function
* @param[in] create - The SdEvent function called to create the source
diff --git a/src/sdeventplus/source/io.hpp b/src/sdeventplus/source/io.hpp
index 724c633..61e9681 100644
--- a/src/sdeventplus/source/io.hpp
+++ b/src/sdeventplus/source/io.hpp
@@ -10,13 +10,18 @@
namespace source
{
+/** @class IO
+ * @brief A wrapper around the sd_event_source IO type
+ * See sd_event_add_io(3) for more information
+ */
class IO : public Base
{
public:
using Callback = std::function<void(IO&, int fd, uint32_t revents)>;
/** @brief Adds a new IO source handler to the Event
- * Executes the callback upon events occurring
+ * This type of source defaults to Enabled::On, executing the
+ * callback for each IO epoll event observed.
*
* @param[in] event - The event to attach the handler
* @param[in] fd - The file descriptor producing the events
diff --git a/src/sdeventplus/source/time.hpp b/src/sdeventplus/source/time.hpp
index 14d4304..c43de7a 100644
--- a/src/sdeventplus/source/time.hpp
+++ b/src/sdeventplus/source/time.hpp
@@ -12,6 +12,10 @@
namespace source
{
+/** @class Time<ClockId>
+ * @brief A wrapper around the sd_event_source time type
+ * See sd_event_add_time(3) for more information
+ */
template <ClockId Id>
class Time : public Base
{
@@ -24,11 +28,14 @@
using Callback = std::function<void(Time& source, TimePoint time)>;
/** @brief Creates a new time event source on the provided event loop
+ * This type of source defaults to Enabled::Oneshot, and needs to be
+ * reconfigured upon each callback.
*
* @param[in] event - The event to attach the handler
* @param[in] time - Absolute time when the callback should be executed
* @param[in] accuracy - Optional amount of error tolerable in time source
* @param[in] callback - The function executed on event dispatch
+ * @throws SdEventError for underlying sd_event errors
*/
Time(const Event& event, TimePoint time, Accuracy accuracy,
Callback&& callback);