source/event: Document header

1 files changed, 48 insertions, 0 deletions

diff --git a/src/sdeventplus/source/event.hpp b/src/sdeventplus/source/event.hpp
index 7df8703..9ab6be7 100644
--- a/src/sdeventplus/source/event.hpp
+++ b/src/sdeventplus/source/event.hpp
@@ -18,35 +18,83 @@ class EventBase : public Base
   protected:
     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
+     *
+     *  @param[in] name   - The name identifying the create function
+     *  @param[in] create - The SdEvent function called to create the source
+     *  @param[in] event  - The event to attach the handler
+     *  @param[in] callback - The function executed on event dispatch
+     *  @throws SdEventError for underlying sd_event errors
+     */
     EventBase(const char* name, CreateFunc create, const Event& event,
               Callback&& callback);
 
   private:
     Callback callback;
 
+    /** @brief Returns a reference to the callback executed for this source
+     *
+     *  @return A reference to the callback
+     */
     const Callback& get_callback() const;
 
+    /** @brief Creates a new source attached to the Event
+     *
+     *  @param[in] name   - The name identifying the create function
+     *  @param[in] create - The SdEvent function called to create the source
+     *  @param[in] event  - The event to attach the handler
+     *  @throws SdEventError for underlying sd_event errors
+     *  @return A new sd_event_source
+     */
     static sd_event_source* create_source(const char* name, CreateFunc create,
                                           const Event& event);
 
+    /** @brief A wrapper around the callback that can be called from sd-event
+     *
+     *  @param[in] source   - The sd_event_source associated with the call
+     *  @param[in] userdata - The provided userdata for the source
+     *  @return 0 on success or a negative errno otherwise
+     */
     static int eventCallback(sd_event_source* source, void* userdata);
 };
 
 class Defer : public EventBase
 {
   public:
+    /** @brief Adds a new defer source handler to the Event
+     *         Executes the callback upon events occurring
+     *
+     *  @param[in] event  - The event to attach the handler
+     *  @param[in] callback - The function executed on event dispatch
+     *  @throws SdEventError for underlying sd_event errors
+     */
     Defer(const Event& event, Callback&& Callback);
 };
 
 class Post : public EventBase
 {
   public:
+    /** @brief Adds a new post source handler to the Event
+     *         Executes the callback upon events occurring
+     *
+     *  @param[in] event  - The event to attach the handler
+     *  @param[in] callback - The function executed on event dispatch
+     *  @throws SdEventError for underlying sd_event errors
+     */
     Post(const Event& event, Callback&& callback);
 };
 
 class Exit : public EventBase
 {
   public:
+    /** @brief Adds a new exit source handler to the Event
+     *         Executes the callback upon events occurring
+     *
+     *  @param[in] event  - The event to attach the handler
+     *  @param[in] callback - The function executed on event dispatch
+     *  @throws SdEventError for underlying sd_event errors
+     */
     Exit(const Event& event, Callback&& callback);
 };