more docs

Author: cwaldren-ld

libs/common/include/config/detail/events.hpp

@@ -7,35 +7,73 @@
 #include "attribute_reference.hpp"
 namespace launchdarkly::config::detail {
 
+/**
+ * Specifies the security regime for event delivery.
+ */
 enum class TransportSecurity {
+    // Plaintext event delivery.
     None = 0,
+    // Event delivery secured by Transport Layer Security.
     TLS = 1,
 };
 
 struct Events {
    public:
     template <typename SDK>
     friend class EventsBuilder;
+    /**
+     * Constructs configuration for the event subsystem.
+     * @param capacity How many events can queue in memory before new events
+     * are dropped.
+     * @param flush_interval How often events are automatically flushed to LaunchDarkly.
+     * @param path The path component of the LaunchDarkly event delivery endpoint.
+     * @param all_attributes_private Whether all attributes should be treated as private or not.
+     * @param private_attrs Which attributes should be treated as private, if all_attributes_private is false.
+     * @param security Whether a plaintext or encrypted client should be used for event delivery.
+     */
     Events(std::size_t capacity,
            std::chrono::milliseconds flush_interval,
            std::string path,
            bool all_attributes_private,
            AttributeReference::SetType private_attrs,
            TransportSecurity security);
-    std::size_t capacity() const;
-    std::chrono::milliseconds flush_interval() const;
-    std::string const& path() const;
-    bool all_attributes_private() const;
-    AttributeReference::SetType const& private_attributes() const;
-    TransportSecurity transport_security() const;
+
+    /**
+     * Capacity of the event processor.
+     */
+    [[nodiscard]] std::size_t capacity() const;
+
+    /**
+     * Flush interval of the event processor, in milliseconds.
+     */
+    [[nodiscard]] std::chrono::milliseconds flush_interval() const;
+
+    /**
+     * Path component of the LaunchDarkly event delivery endpoint.
+     */
+    [[nodiscard]] std::string const& path() const;
+
+    /**
+     * Whether all attributes should be considered private or not.
+     */
+    [[nodiscard]] bool all_attributes_private() const;
+
+    /**
+     * Set of individual attributes that should be considered private.
+     */
+    [[nodiscard]] AttributeReference::SetType const& private_attributes() const;
+
+    /**
+     * Requested transport security.
+     */
+    [[nodiscard]] TransportSecurity transport_security() const;
 
    private:
     std::size_t capacity_;
     std::chrono::milliseconds flush_interval_;
     std::string path_;
     bool all_attributes_private_;
     AttributeReference::SetType private_attributes_;
-
     TransportSecurity transport_security_;
 };
 

libs/common/include/config/detail/events_builder.hpp

@@ -38,7 +38,7 @@ class EventsBuilder {
      * Sets the capacity of the event processor. When more events are generated
      * within the processor's flush interval than this value, events will be
      * dropped.
-     * @param capacity Event capacity.
+     * @param capacity Event queue capacity.
      * @return Reference to this builder.
      */
     EventsBuilder& capacity(std::size_t capacity);
@@ -79,15 +79,22 @@ class EventsBuilder {
     EventsBuilder& all_attributes_private(bool);
 
     /**
-     * Specify an AttributePolicy for individual attributes.
-     * @return
+     * Specify that a set of attributes are private.
+     * @return Reference to this builder.
      */
     EventsBuilder& private_attributes(
         AttributeReference::SetType private_attrs);
 
     /**
-     * Builds Events configuration, if the configuration is valid. If not,
-     * returns an error.
+     * Specify the transport security regime for event delivery. By default,
+     * events are delivered using TLS.
+     * @param regime Security regime.
+     * @return Reference to this builder.
+     */
+    EventsBuilder& transport_security(TransportSecurity regime);
+
+    /**
+     * Builds Events configuration, if the configuration is valid.
      * @return Events config, or error.
      */
     [[nodiscard]] tl::expected<Events, Error> build();

libs/common/src/config/events_builder.cpp

@@ -33,6 +33,13 @@ EventsBuilder<SDK>& EventsBuilder<SDK>::private_attributes(
     return *this;
 }
 
+template <typename SDK>
+EventsBuilder<SDK>& EventsBuilder<SDK>::transport_security(
+    TransportSecurity regime) {
+    config_.transport_security_ = regime;
+    return *this;
+}
+
 template <typename SDK>
 tl::expected<Events, Error> EventsBuilder<SDK>::build() {
     if (config_.capacity() == 0) {