swift: add DrString tool & fix documentation comment issues

.drstring.toml

@@ -0,0 +1,17 @@
+include = [
+    "library/swift/**/*.swift",
+]
+column-limit = 110
+ignore-throws = true
+first-letter = "lowercase"
+vertical-align = true
+empty-patterns = true
+needs-separation = [
+    "description",
+    "parameters",
+]
+parameter-style = "separate"
+align-after-colon = [
+    "throws",
+    "returns",
+]

.github/workflows/format.yml

@@ -37,13 +37,23 @@ jobs:
   swiftlint:
     name: swift_lint
     runs-on: ubuntu-18.04
-    timeout-minutes: 45
+    timeout-minutes: 5
     container:
-      image: ghcr.io/realm/swiftlint:0.46.5
+      image: ghcr.io/realm/swiftlint:0.47.1
     steps:
       - uses: actions/checkout@v1
       - name: 'Run Swift Lint (SwiftLint)'
         run: swiftlint lint --strict
+  drstring:
+    name: drstring
+    runs-on: macos-12
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v1
+        with:
+          submodules: true
+      - name: 'Run DrString'
+        run: ./bazelw run @DrString//:drstring check
   kotlinlint:
     name: kotlin_lint
     runs-on: macos-12

bazel/envoy_mobile_repositories.bzl

@@ -82,6 +82,13 @@ def swift_repos():
         url = "https://github.com/bazelbuild/rules_swift/releases/download/0.27.0/rules_swift.0.27.0.tar.gz",
     )
 
+    http_archive(
+        name = "DrString",
+        build_file_content = """exports_files(["drstring"])""",
+        sha256 = "860788450cf9900613454a51276366ea324d5bfe71d1844106e9c1f1d7dfd82b",
+        url = "https://github.com/dduan/DrString/releases/download/0.5.2/drstring-x86_64-apple-darwin.tar.gz",
+    )
+
     http_archive(
         name = "SwiftLint",
         build_file_content = """exports_files(["swiftlint"])""",

library/swift/filters/AsyncRequestFilter.swift

@@ -15,13 +15,15 @@ public protocol AsyncRequestFilter: RequestFilter {
   /// As with other filter invocations, this will be called on Envoy's main thread, and thus
   /// no additional synchronization is required between this and other invocations.
   ///
-  /// - param headers: Headers, if `stopIteration` was returned from `onRequestHeaders`.
-  /// - param data: Any data that has been buffered where `stopIterationAndBuffer` was returned.
-  /// - param trailers: Trailers, if `stopIteration` was returned from `onRequestTrailers`.
-  /// - param endStream: True, if the stream ended with the previous (and thus, last) invocation.
-  /// - param streamIntel: Internal HTTP stream metrics, context, and other details.
+  /// - parameter headers:     Headers, if `stopIteration` was returned from `onRequestHeaders`.
+  /// - parameter data:        Any data that has been buffered where `stopIterationAndBuffer` was
+  ///                          returned.
+  /// - parameter trailers:    Trailers, if `stopIteration` was returned from `onRequestTrailers`.
+  /// - parameter endStream:   True, if the stream ended with the previous (and thus, last)
+  ///                          invocation.
+  /// - parameter streamIntel: Internal HTTP stream metrics, context, and other details.
   ///
-  /// - return: The resumption status including any HTTP entities that will be forwarded.
+  /// - returns: The resumption status including any HTTP entities that will be forwarded.
   func onResumeRequest(
     headers: RequestHeaders?,
     data: Data?,

library/swift/filters/AsyncResponseFilter.swift

@@ -15,13 +15,15 @@ public protocol AsyncResponseFilter: ResponseFilter {
   /// As with other filter invocations, this will be called on Envoy's main thread, and thus
   /// no additional synchronization is required between this and other invocations.
   ///
-  /// - param headers: Headers, if `stopIteration` was returned from `onResponseHeaders`.
-  /// - param data: Any data that has been buffered where `stopIterationAndBuffer` was returned.
-  /// - param trailers: Trailers, if `stopIteration` was returned from `onReponseTrailers`.
-  /// - param endStream: True, if the stream ended with the previous (and thus, last) invocation.
-  /// - param streamIntel: Internal HTTP stream metrics, context, and other details.
+  /// - parameter headers:     Headers, if `stopIteration` was returned from `onResponseHeaders`.
+  /// - parameter data:        Any data that has been buffered where `stopIterationAndBuffer` was
+  ///                          returned.
+  /// - parameter trailers:    Trailers, if `stopIteration` was returned from `onReponseTrailers`.
+  /// - parameter endStream:   True, if the stream ended with the previous (and thus, last)
+  ///                          invocation.
+  /// - parameter streamIntel: Internal HTTP stream metrics, context, and other details.
   ///
-  /// - return: The resumption status including any HTTP entities that will be forwarded.
+  /// - returns: The resumption status including any HTTP entities that will be forwarded.
   func onResumeResponse(
     headers: ResponseHeaders?,
     data: Data?,

library/swift/filters/Filter.swift

@@ -15,6 +15,8 @@ extension EnvoyHTTPFilterFactory {
 
 extension EnvoyHTTPFilter {
   /// Initialize an EnvoyHTTPFilter using the instance methods of a concrete Filter implementation.
+  ///
+  /// - parameter filter: The contrete `Filter` to wrap.
   convenience init(filter: Filter) {
     self.init()
 

library/swift/grpc/GRPCStreamPrototype.swift

@@ -136,9 +136,10 @@ private enum GRPCMessageProcessor {
   /// Recursively processes a buffer of data, buffering it into messages based on state.
   /// When a message has been fully buffered, `onMessage` will be called with the message.
   ///
-  /// - parameter buffer:    The buffer of data from which to determine state and messages.
-  /// - parameter state:     The current state of the buffering.
-  /// - parameter onMessage: Closure to call when a new message is available.
+  /// - parameter buffer:      The buffer of data from which to determine state and messages.
+  /// - parameter state:       The current state of the buffering.
+  /// - parameter streamIntel: Internal HTTP stream metrics, context, and other details.
+  /// - parameter onMessage:   Closure to call when a new message is available.
   static func processBuffer(_ buffer: inout Data, state: inout State, streamIntel: StreamIntel,
                             onMessage: (_ message: Data, _ streamIntel: StreamIntel) -> Void)
   {

library/swift/stats/Counter.swift

@@ -4,9 +4,14 @@ import Foundation
 @objc
 public protocol Counter: AnyObject {
   /// Increment the counter by the given count.
+  ///
+  /// - parameter count: The count to add to this counter.
   func increment(count: Int)
 
   /// Increment the counter by the given count and along with tags.
+  ///
+  /// - parameter tags:  The tags to attach to this Counter.
+  /// - parameter count: The count to add to this counter.
   func increment(tags: Tags, count: Int)
 }
 

library/swift/stats/CounterImpl.swift

@@ -16,12 +16,17 @@ final class CounterImpl: NSObject, Counter {
   }
 
   /// Increment the counter by the given count.
+  ///
+  /// - parameter count: The count to increment on this counter.
   func increment(count: Int) {
     // TODO(jingwei99) potentially surface error up if engine is nil.
     self.engine?.recordCounterInc(self.series, tags: self.tags.allTags(), count: numericCast(count))
   }
 
   /// Increment the counter by the given count with tags.
+  ///
+  /// - parameter tags:  The tags to attach to this counter.
+  /// - parameter count: The count to increment on this counter.
   func increment(tags: Tags, count: Int) {
     self.engine?.recordCounterInc(self.series, tags: tags.allTags(), count: numericCast(count))
   }

library/swift/stats/Distribution.swift

@@ -4,8 +4,13 @@ import Foundation
 @objc
 public protocol Distribution: AnyObject {
   /// Record a new value to add to the integer distribution.
+  ///
+  /// - parameter value: The value to record.
   func recordValue(value: Int)
 
   /// Record a new value to add to the integer distribution with tags.
+  ///
+  /// - parameter tags:  The tags to attach to this distribution.
+  /// - parameter value: The value to record.
   func recordValue(tags: Tags, value: Int)
 }

library/swift/stats/DistributionImpl.swift

@@ -16,13 +16,18 @@ final class DistributionImpl: NSObject, Distribution {
   }
 
   /// Record a new int value for the distribution.
+  ///
+  /// - parameter value: The value to record.
   func recordValue(value: Int) {
     // TODO(jingwei99) potentially surface error up if engine is nil.
     self.engine?.recordHistogramValue(
       self.series, tags: self.tags.allTags(), value: numericCast(value))
   }
 
   /// Record a new int value for the distribution with tags.
+  ///
+  /// - parameter tags:  The tags to attach to this distribution.
+  /// - parameter value: The value to record.
   func recordValue(tags: Tags, value: Int) {
     // TODO(jingwei99) potentially surface error up if engine is nil.
     self.engine?.recordHistogramValue(self.series, tags: tags.allTags(), value: numericCast(value))

library/swift/stats/Gauge.swift

@@ -3,21 +3,36 @@ import Foundation
 /// A time series gauge.
 @objc
 public protocol Gauge: AnyObject {
-  /// Set the gauge with the given value.
+  /// Set the gauge to the given value.
+  ///
+  /// - parameter value: Set the gauge to the given value.
   func set(value: Int)
 
-  /// Set the gauge with the given value and tags.
+  /// Set the gauge to the given value and tags.
+  ///
+  /// - parameter tags:  The tags to attach to this Gauge.
+  /// - parameter value: Set the gauge to the given value.
   func set(tags: Tags, value: Int)
 
   /// Add the given amount to the gauge.
+  ///
+  /// - parameter amount: Add the given amount to the gauge.
   func add(amount: Int)
 
   /// Add the given amount to the gauge with tags.
+  ///
+  /// - parameter tags:   The tags to attach to this Gauge.
+  /// - parameter amount: Add the given amount to the gauge.
   func add(tags: Tags, amount: Int)
 
   /// Subtract the given amount from the gauge.
+  ///
+  /// - parameter amount: Subtract the given amount from the gauge.
   func sub(amount: Int)
 
   /// Subtract the given amount from the gauge with tags.
+  ///
+  /// - parameter tags:   The tags to attach to this Gauge.
+  /// - parameter amount: Subtract the given amount from the gauge.
   func sub(tags: Tags, amount: Int)
 }

library/swift/stats/GaugeImpl.swift

@@ -16,32 +16,47 @@ final class GaugeImpl: NSObject, Gauge {
   }
 
   /// Set the gauge with the given value.
+  ///
+  /// - parameter value: The value to set.
   func set(value: Int) {
     // TODO(jingwei99) potentially surface error up if engine is nil.
     self.engine?.recordGaugeSet(self.series, tags: self.tags.allTags(), value: numericCast(value))
   }
 
-    /// Set the gauge with the given value and with tags
+  /// Set the gauge with the given value and with tags.
+  ///
+  /// - parameter tags:  The tags to attach to this Gauge.
+  /// - parameter value: The value to set.
   func set(tags: Tags, value: Int) {
     self.engine?.recordGaugeSet(self.series, tags: tags.allTags(), value: numericCast(value))
   }
 
   /// Add the given amount to the gauge.
+  ///
+  /// - parameter amount: The amount to add to this Gauge.
   func add(amount: Int) {
     self.engine?.recordGaugeAdd(self.series, tags: self.tags.allTags(), amount: numericCast(amount))
   }
 
   /// Add the given amount to the gauge with the given tags.
+  ///
+  /// - parameter tags:   The tags to attach to this Gauge.
+  /// - parameter amount: The amount to add to this Gauge.
   func add(tags: Tags, amount: Int) {
     self.engine?.recordGaugeAdd(self.series, tags: tags.allTags(), amount: numericCast(amount))
   }
 
   /// Subtract the given amount from the gauge.
+  ///
+  /// - parameter amount: The amount to subtract from this Gauge.
   func sub(amount: Int) {
     self.engine?.recordGaugeSub(self.series, tags: self.tags.allTags(), amount: numericCast(amount))
   }
 
   /// Subtract the given amount from the gauge with the given tags.
+  ///
+  /// - parameter tags:   The tags to attach to this Gauge.
+  /// - parameter amount: The amount to subtract from this Gauge.
   func sub(tags: Tags, amount: Int) {
     self.engine?.recordGaugeSub(self.series, tags: tags.allTags(), amount: numericCast(amount))
   }

library/swift/stats/Tags.swift

@@ -24,7 +24,7 @@ public class Tags: NSObject {
 
   /// Internal initializer used by builders.
   ///
-  /// - parameter Tags: Tags to set.
+  /// - parameter tags: Tags to set.
   required init(tags: [String: String]) {
     self.tags = tags
     super.init()

library/swift/stats/TagsBuilder.swift

@@ -20,7 +20,7 @@ public class TagsBuilder: NSObject {
 
   /// Replace all values at the provided name with a new set of tag values.
   ///
-  /// - parameter name: The tag name.
+  /// - parameter name:  The tag name.
   /// - parameter value: The value associated to the tag name.
   ///
   /// - returns: This builder.
@@ -43,7 +43,7 @@ public class TagsBuilder: NSObject {
 
   /// Add all tags from dictionary to builder.
   ///
-  /// - parameter name: a dictionary of tags.
+  /// - parameter tags: a dictionary of tags.
   ///
   /// - returns: This builder.
   @discardableResult
@@ -63,7 +63,7 @@ public class TagsBuilder: NSObject {
 
   /// Allows for setting tags that are not publicly mutable (i.e., restricted tags).
   ///
-  /// - parameter name: The tag name.
+  /// - parameter name:  The tag name.
   /// - parameter value: The value associated to the tag name.
   ///
   /// - returns: This builder.

library/swift/stats/Timer.swift

@@ -4,8 +4,13 @@ import Foundation
 @objc
 public protocol Timer: AnyObject {
   /// Record a new duration to add to the timer.
+  ///
+  /// - parameter durationMs: The duration to add in milliseconds.
   func recordDuration(durationMs: Int)
 
   /// Record a new duration to add to the timer along with tags.
+  ///
+  /// - parameter tags:       The tags to attach to this Timer.
+  /// - parameter durationMs: The duration to add in milliseconds.
   func recordDuration(tags: Tags, durationMs: Int)
 }

library/swift/stats/TimerImpl.swift

@@ -16,13 +16,18 @@ final class TimerImpl: NSObject, Timer {
   }
 
   /// Record a new duration value for the distribution.
+  ///
+  /// - parameter durationMs: The duration to record in milliseconds.
   func recordDuration(durationMs: Int) {
     // TODO(jingwei99) potentially surface error up if engine is nil.
     self.engine?.recordHistogramDuration(
       self.series, tags: self.tags.allTags(), durationMs: numericCast(durationMs))
   }
 
   /// Record a new duration value for the distribution with tags.
+  ///
+  /// - parameter tags:       The tags to attach to this timer.
+  /// - parameter durationMs: The duration to record in milliseconds.
   func recordDuration(tags: Tags, durationMs: Int) {
     self.engine?.recordHistogramDuration(
       self.series, tags: tags.allTags(), durationMs: numericCast(durationMs))

tools/check_format.sh

@@ -11,8 +11,10 @@ fi
 if [[ $(uname) == "Darwin" ]]; then
   if [[ "${ENVOY_FORMAT_ACTION}" == "fix" ]]; then
     ./bazelw run --run_under="cd $PWD && " @SwiftLint//:swiftlint -- --fix --quiet 2>/dev/null
+    ./bazelw run @DrString//:drstring format 2>/dev/null
   else
     ./bazelw run --run_under="cd $PWD && " @SwiftLint//:swiftlint -- --strict --quiet 2>/dev/null
+    ./bazelw run @DrString//:drstring check 2>/dev/null
   fi
 fi