diff --git a/.drstring.toml b/.drstring.toml new file mode 100644 index 0000000000..d4c0109a5e --- /dev/null +++ b/.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", +] diff --git a/.github/workflows/format.yml b/.github/workflows/format.yml index de19022d20..30137b0811 100644 --- a/.github/workflows/format.yml +++ b/.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 diff --git a/bazel/envoy_mobile_repositories.bzl b/bazel/envoy_mobile_repositories.bzl index c492901983..1c7459db0e 100644 --- a/bazel/envoy_mobile_repositories.bzl +++ b/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"])""", diff --git a/library/swift/filters/AsyncRequestFilter.swift b/library/swift/filters/AsyncRequestFilter.swift index 8ad8076e08..b8692fa9d9 100644 --- a/library/swift/filters/AsyncRequestFilter.swift +++ b/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?, diff --git a/library/swift/filters/AsyncResponseFilter.swift b/library/swift/filters/AsyncResponseFilter.swift index 51899ecd4d..2e9ddc6775 100644 --- a/library/swift/filters/AsyncResponseFilter.swift +++ b/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?, diff --git a/library/swift/filters/Filter.swift b/library/swift/filters/Filter.swift index 4272708cc6..ebd87a5024 100644 --- a/library/swift/filters/Filter.swift +++ b/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() diff --git a/library/swift/grpc/GRPCStreamPrototype.swift b/library/swift/grpc/GRPCStreamPrototype.swift index adb7ce8a56..03629f648e 100644 --- a/library/swift/grpc/GRPCStreamPrototype.swift +++ b/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) { diff --git a/library/swift/stats/Counter.swift b/library/swift/stats/Counter.swift index 57c84c5755..4ab153ed61 100644 --- a/library/swift/stats/Counter.swift +++ b/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) } diff --git a/library/swift/stats/CounterImpl.swift b/library/swift/stats/CounterImpl.swift index 24c9eba9bf..baf031048a 100644 --- a/library/swift/stats/CounterImpl.swift +++ b/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)) } diff --git a/library/swift/stats/Distribution.swift b/library/swift/stats/Distribution.swift index 5a5a3be408..658f52d904 100644 --- a/library/swift/stats/Distribution.swift +++ b/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) } diff --git a/library/swift/stats/DistributionImpl.swift b/library/swift/stats/DistributionImpl.swift index cfb407e951..b3c9e4d507 100644 --- a/library/swift/stats/DistributionImpl.swift +++ b/library/swift/stats/DistributionImpl.swift @@ -16,6 +16,8 @@ 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( @@ -23,6 +25,9 @@ final class DistributionImpl: NSObject, Distribution { } /// 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)) diff --git a/library/swift/stats/Gauge.swift b/library/swift/stats/Gauge.swift index 9175ba8f65..78933b7ddd 100644 --- a/library/swift/stats/Gauge.swift +++ b/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) } diff --git a/library/swift/stats/GaugeImpl.swift b/library/swift/stats/GaugeImpl.swift index 42053772b0..b1cd4a1e7c 100644 --- a/library/swift/stats/GaugeImpl.swift +++ b/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)) } diff --git a/library/swift/stats/Tags.swift b/library/swift/stats/Tags.swift index 9e9ff7eaa1..ef49e7f4a0 100644 --- a/library/swift/stats/Tags.swift +++ b/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() diff --git a/library/swift/stats/TagsBuilder.swift b/library/swift/stats/TagsBuilder.swift index a34bbf2414..8f79361385 100644 --- a/library/swift/stats/TagsBuilder.swift +++ b/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. diff --git a/library/swift/stats/Timer.swift b/library/swift/stats/Timer.swift index e6b4a8786f..b7e4c527e6 100644 --- a/library/swift/stats/Timer.swift +++ b/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) } diff --git a/library/swift/stats/TimerImpl.swift b/library/swift/stats/TimerImpl.swift index 410af1890a..2bd96de8fa 100644 --- a/library/swift/stats/TimerImpl.swift +++ b/library/swift/stats/TimerImpl.swift @@ -16,6 +16,8 @@ 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( @@ -23,6 +25,9 @@ final class TimerImpl: NSObject, Timer { } /// 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)) diff --git a/tools/check_format.sh b/tools/check_format.sh index fdab97b616..d1373d26fb 100755 --- a/tools/check_format.sh +++ b/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