swift: fix docstrings and docstring linter

.drstring.toml

@@ -1,7 +1,7 @@
 include = [
-    "library/swift/**/*.swift",
+    "library/swift/**.swift",
 ]
-column-limit = 110
+column-limit = 100
 ignore-throws = true
 first-letter = "lowercase"
 vertical-align = true

library/swift/Engine.swift

@@ -7,7 +7,7 @@ public protocol Engine: AnyObject {
   /// - returns: A client for opening and managing HTTP streams.
   func streamClient() -> StreamClient
 
-  /// A client for recording time series metrics.
+  /// - returns: A client for recording time series metrics.
   func pulseClient() -> PulseClient
 
   /// Flush the stats sinks outside of a flushing interval.

library/swift/EngineBuilder.swift

@@ -102,7 +102,7 @@ open class EngineBuilder: NSObject {
   /// Add a rate at which to refresh DNS in case of DNS failure.
   ///
   /// - parameter base: Base rate in seconds.
-  /// - parameter max: Max rate in seconds.
+  /// - parameter max:  Max rate in seconds.
   ///
   /// - returns: This builder.
   @discardableResult
@@ -304,7 +304,7 @@ open class EngineBuilder: NSObject {
 
   /// Add a custom idle timeout for HTTP streams. Defaults to 15 seconds.
   ///
-  /// - parameter streamIdleSeconds: Idle timeout for HTTP streams.
+  /// - parameter streamIdleTimeoutSeconds: Idle timeout for HTTP streams.
   ///
   /// - returns: This builder.
   @discardableResult
@@ -315,7 +315,7 @@ open class EngineBuilder: NSObject {
 
   /// Add a custom per try idle timeout for HTTP streams. Defaults to 15 seconds.
   ///
-  /// - parameter perTryIdleSeconds: Idle timeout for HTTP streams.
+  /// - parameter perTryIdleTimeoutSeconds: Idle timeout for HTTP streams.
   ///
   /// - returns: This builder.
   @discardableResult
@@ -370,7 +370,7 @@ open class EngineBuilder: NSObject {
 
   /// Add a string accessor to this Envoy Client.
   ///
-  /// - parameter name: the name of the accessor.
+  /// - parameter name:     the name of the accessor.
   /// - parameter accessor: lambda to access a string from the platform layer.
   ///
   /// - returns: This builder.
@@ -382,7 +382,7 @@ open class EngineBuilder: NSObject {
 
   /// Register a key-value store implementation for internal use.
   ///
-  /// - parameter name: the name of the KV store.
+  /// - parameter name:          the name of the KV store.
   /// - parameter keyValueStore: the KV store implementation.
   ///
   /// - returns: This builder.
@@ -428,6 +428,8 @@ open class EngineBuilder: NSObject {
   /// Configure how the engine observes network reachability state changes.
   /// Defaults to `.pathMonitor`.
   ///
+  /// - parameter mode: The mode to use.
+  ///
   /// - returns: This builder.
   @discardableResult
   public func setNetworkMonitoringMode(_ mode: NetworkMonitoringMode) -> Self {
@@ -481,6 +483,9 @@ open class EngineBuilder: NSObject {
 
   /// Builds and runs a new `Engine` instance with the provided configuration.
   ///
+  /// - note: Must be strongly retained in order for network requests to be performed correctly.
+  ///
+  /// - returns: The built `Engine`.
   public func build() -> Engine {
     let engine = self.engineType.init(runningCallback: self.onEngineRunning, logger: self.logger,
                                       eventTracker: self.eventTracker,
@@ -539,6 +544,11 @@ open class EngineBuilder: NSObject {
   /// A new instance of this engine will be created when `build()` is called.
   /// Used for testing, as initializing with `EnvoyEngine.Type` results in a
   /// segfault: https://github.com/envoyproxy/envoy-mobile/issues/334
+  ///
+  /// - parameter engineType: The specific implementation of `EnvoyEngine` to use for starting
+  ///                         Envoy.
+  ///
+  /// - returns: This builder.
   @discardableResult
   func addEngineType(_ engineType: EnvoyEngine.Type) -> Self {
     self.engineType = engineType

library/swift/EngineImpl.swift

@@ -29,19 +29,19 @@ final class EngineImpl: NSObject {
 
   /// Initialize a new Envoy instance using a typed configuration.
   ///
-  /// - parameter config:          Configuration to use for starting Envoy.
-  /// - parameter logLevel:        Log level to use for this instance.
-  /// - parameter engine:          The underlying engine to use for starting Envoy.
+  /// - parameter config:   Configuration to use for starting Envoy.
+  /// - parameter logLevel: Log level to use for this instance.
+  /// - parameter engine:   The underlying engine to use for starting Envoy.
   convenience init(config: EnvoyConfiguration, logLevel: LogLevel = .info, engine: EnvoyEngine) {
     self.init(configType: .standard(config: config), logLevel: logLevel, engine: engine)
   }
 
   /// Initialize a new Envoy instance using a string configuration.
   ///
-  /// - parameter yaml:            Template yaml to use as basis for configuration.
-  /// - parameter config:          Configuration to use for starting Envoy.
-  /// - parameter logLevel:        Log level to use for this instance.
-  /// - parameter engine:          The underlying engine to use for starting Envoy.
+  /// - parameter yaml:     Template yaml to use as basis for configuration.
+  /// - parameter config:   Configuration to use for starting Envoy.
+  /// - parameter logLevel: Log level to use for this instance.
+  /// - parameter engine:   The underlying engine to use for starting Envoy.
   convenience init(yaml: String, config: EnvoyConfiguration, logLevel: LogLevel = .info,
                    engine: EnvoyEngine)
   {

library/swift/HeadersBuilder.swift

@@ -30,7 +30,7 @@ public class HeadersBuilder: NSObject {
 
   /// Replace all values at the provided name with a new set of header values.
   ///
-  /// - parameter name: The header name.
+  /// - parameter name:  The header name.
   /// - parameter value: The value associated to the header name.
   ///
   /// - returns: This builder.
@@ -63,7 +63,7 @@ public class HeadersBuilder: NSObject {
 
   /// Allows for setting headers that are not publicly mutable (i.e., restricted headers).
   ///
-  /// - parameter name: The header name.
+  /// - parameter name:  The header name.
   /// - parameter value: The value associated to the header name.
   ///
   /// - returns: This builder.

library/swift/KeyValueStore.swift

@@ -5,12 +5,21 @@ import Foundation
 /// key-value store implementation that may be made accessible to native Envoy Mobile code.
 public protocol KeyValueStore {
   /// Read a value from the key value store implementation.
+  ///
+  /// - parameter key: The key whose value should be read.
+  ///
+  /// - returns: The value read for the key if it was found.
   func readValue(forKey key: String) -> String?
 
   /// Save a value to the key value store implementation.
+  ///
+  /// - parameter value: The value to save.
+  /// - parameter key:   The key to associate with the saved value.
   func saveValue(_ value: String, toKey key: String)
 
   /// Remove a value from the key value store implementation.
+  ///
+  /// - parameter key: The key whose value should be removed.
   func removeKey(_ key: String)
 }
 

library/swift/PulseClient.swift

@@ -12,7 +12,7 @@ public protocol PulseClient: AnyObject {
   func counter(elements: [Element]) -> Counter
 
   /// - parameter elements: Elements to identify a counter
-  /// - parameter tags: Tags of the counter
+  /// - parameter tags:     Tags of the counter
   ///
   /// - returns: A Counter based on the joined elements and along with tags
   func counter(elements: [Element], tags: Tags) -> Counter
@@ -23,8 +23,8 @@ public protocol PulseClient: AnyObject {
   func gauge(elements: [Element]) -> Gauge
 
   /// - parameter elements: Elements to identify a gauge
-  /// - parameter tags: Tags of the gauge
-  /// -
+  /// - parameter tags:     Tags of the gauge
+  ///
   /// - returns: A Gauge based on the joined elements and along with tags
   func gauge(elements: [Element], tags: Tags) -> Gauge
 
@@ -34,10 +34,10 @@ public protocol PulseClient: AnyObject {
   func timer(elements: [Element]) -> Timer
 
   /// - parameter elements: Elements to identify a timer
-  /// - parameter tags: Tags of the timer
+  /// - parameter tags:     Tags of the timer
   ///
   /// - returns: A Timer based on the joined elements and with tags
-  ///   to track a distribution of durations
+  ///            to track a distribution of durations
   func timer(elements: [Element], tags: Tags) -> Timer
 
   /// - parameter elements: Elements to identify a distribution
@@ -46,7 +46,7 @@ public protocol PulseClient: AnyObject {
   func distribution(elements: [Element]) -> Distribution
 
   /// - parameter elements: Elements to identify a distribution
-  /// - parameter tags: Tags of the distribution
+  /// - parameter tags:     Tags of the distribution
   ///
   /// - returns: A Distribution based on the joined elements and along with tags
   func distribution(elements: [Element], tags: Tags) -> Distribution

library/swift/RetryPolicyMapper.swift

@@ -35,6 +35,8 @@ extension RetryPolicy {
   /// Initialize the retry policy from a set of headers.
   ///
   /// - parameter headers: The headers with which to initialize the retry policy.
+  ///
+  /// - returns: The `RetryPolicy` if one was derived from the headers.
   static func from(headers: Headers) -> RetryPolicy? {
     guard let maxRetryCount = headers.value(forName: "x-envoy-max-retries")?
       .first.flatMap(UInt.init) else

library/swift/StreamPrototype.swift

@@ -52,7 +52,8 @@ public class StreamPrototype: NSObject {
   /// reduced overall throughput, depending on usage.
   ///
   /// - parameter enabled: Whether explicit flow control will be enabled for the stream.
-  /// - returns:  This stream, for chaining syntax.
+  ///
+  /// - returns: This stream, for chaining syntax.
   public func setExplicitFlowControl(enabled: Bool) -> StreamPrototype {
     self.explicitFlowControl = enabled
     return self