internal: Add header documentation
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 internal
{
+/** @class SdEvent
+ * @brief Overridable direct sd_event interface
+ */
class SdEvent
{
public:
@@ -104,6 +107,10 @@
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 @@
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 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 @@
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 test
{
+/** @class SdEventMock
+ * @brief sd_event mocked implementation
+ * @details Uses googlemock to handle all sd_event calls
+ */
class SdEventMock : public internal::SdEvent
{
public: