DocC setup

Author: yim-lee

[email protected]

@@ -0,0 +1,36 @@
+// swift-tools-version:5.6
+
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftStatsdClient open source project
+//
+// Copyright (c) 2022 the SwiftStatsdClient project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftStatsdClient project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-statsd-client",
+    products: [
+        .library(name: "StatsdClient", targets: ["StatsdClient"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
+    ],
+    targets: [
+        .target(name: "StatsdClient", dependencies: [
+            .product(name: "CoreMetrics", package: "swift-metrics"),
+            .product(name: "NIO", package: "swift-nio"),
+        ]),
+        .testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
+    ]
+)

README.md

@@ -1,36 +1,36 @@
 # SwiftStatsDClient
 
 a metrics backend for [swift-metrics](https://github.com/apple/swift-metrics) that uses the [statsd](https://github.com/b/statsd_spec) protocol, and can be used to integrate applications with observability solutions that support `statsd` including:
-* [aws](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-custom-metrics-statsd.html)
-* [azure](https://docs.microsoft.com/en-us/azure/azure-monitor/platform/data-platform)
-* [google cloud](https://cloud.google.com/monitoring/agent/plugins/statsd)
-* [ibm cloud](https://cloud.ibm.com/catalog/services/ibm-cloud-monitoring-with-sysdig)
-* [grafana](https://grafana.com)
-* [graphite](https://graphiteapp.org)
-* many others
+* [AWS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-custom-metrics-statsd.html)
+* [Azure](https://docs.microsoft.com/en-us/azure/azure-monitor/platform/data-platform)
+* [Google Cloud](https://cloud.google.com/monitoring/agent/plugins/statsd)
+* [IBM Cloud](https://cloud.ibm.com/catalog/services/ibm-cloud-monitoring-with-sysdig)
+* [Grafana](https://grafana.com)
+* [Graphite](https://graphiteapp.org)
+* Many others
 
 ## Getting started
 
-create an instance of the `StatsdClient` and boostrap the `MetricsSystem` in your application's main:
+Create an instance of the `StatsdClient` and boostrap the `MetricsSystem` in your application's `main`:
 
 ```swift
 let statsdClient = try StatsdClient(host: host, port: port)
 MetricsSystem.bootstrap(statsdClient)
 ```
 
-see https://github.com/apple/swift-metrics#selecting-a-metrics-backend-implementation-applications-only
+See [selecting a metrics backend implementation](https://github.com/apple/swift-metrics#selecting-a-metrics-backend-implementation-applications-only) for more information.
 
-remeber to also shutdown the client before you application terminates:
+Remember to also shutdown the client before you application terminates:
 
 ```swift
 statsdClient.shutdown()
 ```
 
 ## Architecture
 
-the statsd client uses [swift-nio](https://github.com/apple/swift-nio) to establish a UDP connection to the statsd server
+`StatsdClient` uses [SwiftNIO](https://github.com/apple/swift-nio) to establish a UDP connection to the `statsd` server.
 
-metrics types are mapped as follwoing:
+Metrics types are mapped as following:
 * Counter -> Counter
 * Gauge -> Gauge
 * Recorder -> Histogram

Sources/StatsdClient/Documentation.docc/index.md

@@ -0,0 +1,49 @@
+# ``StatsdClient``
+
+A metrics backend implementation using the StatsD protocol.
+
+## Overview
+
+StatsdClient is a metrics backend for [SwiftMetrics](https://github.com/apple/swift-metrics) that uses the [StatsD](https://github.com/b/statsd_spec) protocol, and can be used to integrate applications with observability solutions that support StatsD including:
+* [AWS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-custom-metrics-statsd.html)
+* [Azure](https://docs.microsoft.com/en-us/azure/azure-monitor/platform/data-platform)
+* [Google Cloud](https://cloud.google.com/monitoring/agent/plugins/statsd)
+* [IBM Cloud](https://cloud.ibm.com/catalog/services/ibm-cloud-monitoring-with-sysdig)
+* [Grafana](https://grafana.com)
+* [Graphite](https://graphiteapp.org)
+* Many others
+
+## Getting started
+
+Create an instance of the ``StatsdClient/StatsdClient`` and boostrap the `MetricsSystem` in your application's `main`:
+
+```swift
+let statsdClient = try StatsdClient(host: host, port: port)
+MetricsSystem.bootstrap(statsdClient)
+```
+
+See [selecting a metrics backend implementation](https://github.com/apple/swift-metrics#selecting-a-metrics-backend-implementation-applications-only) for more information.
+
+Remember to also shutdown the client before you application terminates:
+
+```swift
+statsdClient.shutdown()
+```
+
+## Architecture
+
+``StatsdClient/StatsdClient`` uses [SwiftNIO](https://github.com/apple/swift-nio) to establish a UDP connection to the `statsd` server.
+
+Metrics types are mapped as following:
+* Counter -> Counter
+* Gauge -> Gauge
+* Recorder -> Histogram
+* Timer -> Timer
+                                              
+## Topics
+                                              
+### Metrics API
+
+- ``StatsdClient/makeCounter(label:dimensions:)``
+- ``StatsdClient/makeRecorder(label:dimensions:aggregate:)``
+- ``StatsdClient/makeTimer(label:dimensions:)``

Sources/StatsdClient/StatsdClient.swift

@@ -2,7 +2,7 @@
 //
 // This source file is part of the SwiftStatsdClient open source project
 //
-// Copyright (c) 2019 the SwiftStatsdClient project authors
+// Copyright (c) 2019-2022 the SwiftStatsdClient project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -26,12 +26,12 @@ public final class StatsdClient: MetricsFactory {
     private var timers = [String: TimerHandler]() // protected by a lock
     private let lock = Lock()
 
-    /// Create a new instance of `StatsdClient`
+    /// Create a new instance of `StatsdClient`.
     ///
-    /// - parameters:
-    ///     - eventLoopGroupProvider: The `EventLoopGroupProvider` to use, uses`createNew` strategy by default.
-    ///     - host: The `statsd` server host.
-    ///     - port: The `statsd` server port.
+    /// - Parameters:
+    ///   - eventLoopGroupProvider: The ``EventLoopGroupProvider`` to use, uses ``EventLoopGroupProvider/createNew`` strategy by default.
+    ///   - host: The `statsd` server host.
+    ///   - port: The `statsd` server port.
     public init(
         eventLoopGroupProvider: EventLoopGroupProvider = .createNew,
         host: String,
@@ -42,12 +42,12 @@ public final class StatsdClient: MetricsFactory {
         self.client = Client(eventLoopGroupProvider: eventLoopGroupProvider, address: address, metricNameSanitizer: metricNameSanitizer)
     }
 
-    /// Shutdown the client. This is a noop when using a `shared` `EventLoopGroupProvider` strategy.
+    /// Shutdown the client. This is a noop when using the ``EventLoopGroupProvider/shared(_:)`` strategy.
     ///
-    /// - Note: It is required to call `shutdown` before terminating the program. `StatsdClient` client will assert it was cleanly shut down as part of it destructor.
+    /// - Note: It is required to call this method before terminating the program. `StatsdClient` will assert it was cleanly shut down as part of its destructor.
     ///
-    /// - parameters:
-    ///     - callback: A caalback for when shutdown is complete
+    /// - Parameters:
+    ///   - callback: A callback for when shutdown is complete.
     public func shutdown(_ callback: @escaping (Error?) -> Void) {
         self.client.shutdown(callback)
     }

scripts/soundness.sh

@@ -3,7 +3,7 @@
 ##
 ## This source file is part of the SwiftStatsdClient open source project
 ##
-## Copyright (c) 2019 the SwiftStatsdClient project authors
+## Copyright (c) 2019-2022 the SwiftStatsdClient project authors
 ## Licensed under Apache License v2.0
 ##
 ## See LICENSE.txt for license information
@@ -14,8 +14,14 @@
 ##===----------------------------------------------------------------------===##
 
 set -eu
+
 here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
+function replace_acceptable_years() {
+    # this needs to replace all acceptable forms with 'YEARS'
+    sed -e 's/20[12][901]-202[012]/YEARS/' -e 's/2019/YEARS/' -e 's/202[012]/YEARS/'
+}
+
 printf "=> Checking for unacceptable language... "
 # This greps for unacceptable terminology. The square bracket[s] are so that
 # "git grep" doesn't find the lines that greps :).
@@ -67,14 +73,14 @@ for language in swift-or-c bash dtrace; do
   matching_files=( -name '*' )
   case "$language" in
       swift-or-c)
-        exceptions=( -name c_nio_http_parser.c -o -name c_nio_http_parser.h -o -name cpp_magic.h -o -name Package.swift -o -name CNIOSHA1.h -o -name c_nio_sha1.c -o -name ifaddrs-android.c -o -name ifaddrs-android.h)
+        exceptions=( -name c_nio_http_parser.c -o -name c_nio_http_parser.h -o -name cpp_magic.h -o -name Package.swift -o -name [email protected] -o -name CNIOSHA1.h -o -name c_nio_sha1.c -o -name ifaddrs-android.c -o -name ifaddrs-android.h)
         matching_files=( -name '*.swift' -o -name '*.c' -o -name '*.h' )
         cat > "$tmp" <<"EOF"
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftStatsdClient open source project
 //
-// Copyright (c) 2019 the SwiftStatsdClient project authors
+// Copyright (c) YEARS the SwiftStatsdClient project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -93,7 +99,7 @@ EOF
 ##
 ## This source file is part of the SwiftStatsdClient open source project
 ##
-## Copyright (c) 2019 the SwiftStatsdClient project authors
+## Copyright (c) YEARS the SwiftStatsdClient project authors
 ## Licensed under Apache License v2.0
 ##
 ## See LICENSE.txt for license information
@@ -112,7 +118,7 @@ EOF
  *
  *  This source file is part of the SwiftStatsdClient open source project
  *
- *  Copyright (c) 2019 the SwiftStatsdClient project authors
+ *  Copyright (c) YEARS the SwiftStatsdClient project authors
  *  Licensed under Apache License v2.0
  *
  *  See LICENSE.txt for license information
@@ -137,7 +143,7 @@ EOF
       \( \! -path './.build/*' -a \
       \( "${matching_files[@]}" \) -a \
       \( \! \( "${exceptions[@]}" \) \) \) | while read line; do
-      if [[ "$(cat "$line" | head -n $expected_lines | shasum)" != "$expected_sha" ]]; then
+      if [[ "$(cat "$line" | replace_acceptable_years | head -n $expected_lines | shasum)" != "$expected_sha" ]]; then
         printf "\033[0;31mmissing headers in file '$line'!\033[0m\n"
         diff -u <(cat "$line" | head -n $expected_lines) "$tmp"
         exit 1