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>

4 files changed, 24 insertions, 3 deletions

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 @@ namespace source
 
 /** @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 @@ class Child : public Base
     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 sdeventplus
 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 @@ class EventBase : public Base
     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 sdeventplus
 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 sdeventplus
 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 @@ class Time : public Base
     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);