internal: Add header documentation

4 files changed, 53 insertions, 2 deletions

diff --git a/src/sdeventplus/internal/sdevent.hpp b/src/sdeventplus/internal/sdevent.hpp
index 80a321c..8f2e608 100644
--- a/src/sdeventplus/internal/sdevent.hpp
+++ b/src/sdeventplus/internal/sdevent.hpp
@@ -7,6 +7,9 @@ namespace sdeventplus
 namespace internal
 {
 
+/** @class SdEvent
+ *  @brief Overridable direct sd_event interface
+ */
 class SdEvent
 {
   public:
@@ -104,6 +107,10 @@ class SdEvent
                                               pid_t* pid) const = 0;
 };
 
+/** @class SdEventImpl
+ *  @brief sd_event concrete implementation
+ *  @details Uses libsystemd to handle all sd_event calls
+ */
 class SdEventImpl : public SdEvent
 {
   public:
@@ -204,6 +211,8 @@ class SdEventImpl : public SdEvent
                                       pid_t* pid) const override;
 };
 
+/** @brief Default instantiation of sd_event
+ */
 extern SdEventImpl sdevent_impl;
 
 } // namespace internal
diff --git a/src/sdeventplus/internal/sdref.hpp b/src/sdeventplus/internal/sdref.hpp
index 12e395f..bc3a950 100644
--- a/src/sdeventplus/internal/sdref.hpp
+++ b/src/sdeventplus/internal/sdref.hpp
@@ -9,24 +9,59 @@ namespace sdeventplus
 namespace internal
 {
 
+/** @class SdRef
+ *  @brief Takes and releases references to T objects
+ *  @details Used primarily as an RAII wrapper around sd_event
+ *           and sd_event_source object references.
+ */
 template <typename T>
 class SdRef
 {
   public:
+    /** @brief The type signature of ref / deref functions
+     */
     using Func = std::function<T*(const SdEvent*, T*)>;
 
+    /** @brief Constructs a new reference holder
+     *         This constructor calls take_ref on ref
+     *
+     *  @param[in] ref         - Object which is referenced
+     *  @param[in] take_ref    - Function used to take references
+     *  @param[im] release_ref - Function used to release references
+     *  @param[in] sdevent     - Optional underlying sd_event implementation
+     */
     SdRef(T* ref, Func take_ref, Func release_ref,
           const SdEvent* sdevent = &sdevent_impl);
+
+    /** @brief Constructs a new reference holder
+     *         Does not take a new reference on the passed ref
+     *
+     *  @param[in] ref         - Object which is referenced
+     *  @param[in] take_ref    - Function used to take references
+     *  @param[im] release_ref - Function used to release references
+     *  @param[in]             - Denotes no reference taken during construction
+     *  @param[in] sdevent     - Optional underlying sd_event implementation
+     */
     SdRef(T* ref, Func take_ref, Func release_ref, std::false_type,
           const SdEvent* sdevent = &sdevent_impl);
-    virtual ~SdRef();
 
+    virtual ~SdRef();
     SdRef(const SdRef& other);
     SdRef& operator=(const SdRef& other);
     SdRef(SdRef&& other);
     SdRef& operator=(SdRef&& other);
 
+    /** @brief Determines if a reference is currently being held
+     *
+     *  @return 'true' if a reference is held
+     *          'false' if empty
+     */
     explicit operator bool() const;
+
+    /** @brief Get a pointer to the object being referenced
+     *
+     * @return The object pointer
+     */
     T* get() const;
 
   private:
diff --git a/src/sdeventplus/internal/utils.hpp b/src/sdeventplus/internal/utils.hpp
index 47a019b..ce9342d 100644
--- a/src/sdeventplus/internal/utils.hpp
+++ b/src/sdeventplus/internal/utils.hpp
@@ -17,7 +17,10 @@ using SdEventDuration =
 namespace internal
 {
 
-// Helpers for sd_event callbacks to handle exceptions gracefully
+/** @brief Handle sd_event callback exception gracefully
+ *  @details A generic wrapper that turns exceptions into
+ *           error messages and return codes.
+ */
 template <typename Func, typename... Args>
 inline int performCallback(const char* name, Func func, Args... args)
 {
diff --git a/src/sdeventplus/test/sdevent.hpp b/src/sdeventplus/test/sdevent.hpp
index 5079a99..366cb67 100644
--- a/src/sdeventplus/test/sdevent.hpp
+++ b/src/sdeventplus/test/sdevent.hpp
@@ -9,6 +9,10 @@ namespace sdeventplus
 namespace test
 {
 
+/** @class SdEventMock
+ *  @brief sd_event mocked implementation
+ *  @details Uses googlemock to handle all sd_event calls
+ */
 class SdEventMock : public internal::SdEvent
 {
   public: