Skip to content

Commit

Permalink
Fix API documentation (#24)
Browse files Browse the repository at this point in the history 
Motivation:

API documentation contains typos and grammatical errors.

Modifications:

Fix typos and grammatical errors. Update to use code syntax where
appropriate.

Result:

Eliminate typos and grammatical errors found.
  • Loading branch information
@yim-lee @tomerd
yim-lee authored and tomerd committed Apr 25, 2019
1 parent ecdc7be commit e7de070
Showing 1 changed file with 48 additions and 48 deletions.
96 changes: 48 additions & 48 deletions Sources/CoreMetrics/Metrics.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,21 +36,21 @@ public protocol CounterHandler: AnyObject {

/// A counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero.
/// For example, you can use a counter to represent the number of requests served, tasks completed, or errors.
/// This is the user facing Counter API. Its behavior depends on the `CounterHandler` implementation
/// This is the user facing Counter API. Its behavior depends on the `CounterHandler` implementation.
public class Counter {
@usableFromInline
var handler: CounterHandler
public let label: String
public let dimensions: [(String, String)]

/// Create a new Counter.
/// Create a new `Counter`.
///
/// This initializer provides an escape hatch for situations one must use a custom factory instead of the gloabl one
/// we do not expect this API to be used in normal circumstances, so if you find yourself using it make sure its for a good reason.
/// This initializer provides an escape hatch for situations where one must use a custom factory instead of the global one.
/// We do not expect this API to be used in normal circumstances, so if you find yourself using it make sure it's for a good reason.
///
/// - parameters:
/// - label: The label for the Counter.
/// - dimensions: The dimensions for the Counter.
/// - label: The label for the `Counter`.
/// - dimensions: The dimensions for the `Counter`.
/// - handler: The custom backend.
public init(label: String, dimensions: [(String, String)], handler: CounterHandler) {
self.label = label
Expand Down Expand Up @@ -81,18 +81,18 @@ public class Counter {
}

public extension Counter {
/// Create a new Counter.
/// Create a new `Counter`.
///
/// - parameters:
/// - label: The label for the Counter.
/// - dimensions: The dimensions for the Counter.
/// - label: The label for the `Counter`.
/// - dimensions: The dimensions for the `Counter`.
convenience init(label: String, dimensions: [(String, String)] = []) {
let handler = MetricsSystem.factory.makeCounter(label: label, dimensions: dimensions)
self.init(label: label, dimensions: dimensions, handler: handler)
}

/// Signal the underlying metrics library that this counter will never be updated again.
/// In response library MAY decide to eagerly release any resources held by this counter.
/// In response the library MAY decide to eagerly release any resources held by this `Counter`.
@inlinable
func destroy() {
MetricsSystem.factory.destroyCounter(self.handler)
Expand Down Expand Up @@ -123,23 +123,23 @@ public protocol RecorderHandler: AnyObject {
func record(_ value: Double)
}

/// A recorder collects observations within a time window (usually things like response sizes) and *can* provide aggregated information about the data sample, for example count, sum, min, max and various quantiles.
/// This is the user facing Recorder API. Its behavior depends on the `RecorderHandler` implementation
/// A recorder collects observations within a time window (usually things like response sizes) and *can* provide aggregated information about the data sample, for example, count, sum, min, max and various quantiles.
/// This is the user facing Recorder API. Its behavior depends on the `RecorderHandler` implementation.
public class Recorder {
@usableFromInline
var handler: RecorderHandler
public let label: String
public let dimensions: [(String, String)]
public let aggregate: Bool

/// Create a new Recorder.
/// Create a new `Recorder`.
///
/// This initializer provides an escape hatch for situations one must use a custom factory instead of the gloabl one
/// we do not expect this API to be used in normal circumstances, so if you find yourself using it make sure its for a good reason.
/// This initializer provides an escape hatch for situations where one must use a custom factory instead of the global one.
/// We do not expect this API to be used in normal circumstances, so if you find yourself using it make sure it's for a good reason.
///
/// - parameters:
/// - label: The label for the Recorder.
/// - dimensions: The dimensions for the Recorder.
/// - label: The label for the `Recorder`.
/// - dimensions: The dimensions for the `Recorder`.
/// - handler: The custom backend.
public init(label: String, dimensions: [(String, String)], aggregate: Bool, handler: RecorderHandler) {
self.label = label
Expand Down Expand Up @@ -168,33 +168,33 @@ public class Recorder {
}

public extension Recorder {
/// Create a new Recorder.
/// Create a new `Recorder`.
///
/// - parameters:
/// - label: The label for the Recorder.
/// - dimensions: The dimensions for the Recorder.
/// - label: The label for the `Recorder`.
/// - dimensions: The dimensions for the `Recorder`.
convenience init(label: String, dimensions: [(String, String)] = [], aggregate: Bool = true) {
let handler = MetricsSystem.factory.makeRecorder(label: label, dimensions: dimensions, aggregate: aggregate)
self.init(label: label, dimensions: dimensions, aggregate: aggregate, handler: handler)
}

/// Signal the underlying metrics library that this recorder will never be updated again.
/// In response library MAY decide to eagerly release any resources held by this recorder.
/// In response the library MAY decide to eagerly release any resources held by this `Recorder`.
@inlinable
func destroy() {
MetricsSystem.factory.destroyRecorder(self.handler)
}
}

/// A Gauge is a metric that represents a single numerical value that can arbitrarily go up and down.
/// A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.
/// Gauges are typically used for measured values like temperatures or current memory usage, but also "counts" that can go up and down, like the number of active threads.
/// Gauges are modeled as `Recorder` with a sample size of 1 and that does not perform any aggregation.
public class Gauge: Recorder {
/// Create a new Gauge.
/// Create a new `Gauge`.
///
/// - parameters:
/// - label: The label for the Gauge.
/// - dimensions: The dimensions for the Gauge.
/// - label: The label for the `Gauge`.
/// - dimensions: The dimensions for the `Gauge`.
public convenience init(label: String, dimensions: [(String, String)] = []) {
self.init(label: label, dimensions: dimensions, aggregate: false)
}
Expand All @@ -219,23 +219,23 @@ public protocol TimerHandler: AnyObject {
func recordNanoseconds(_ duration: Int64)
}

/// A timer collects observations within a time window (usually things like request durations) and provides aggregated information about the data sample.
/// For example min, max and various quantiles. It is similar to a `Recorder` but specialized for values that represent durations.
/// This is the user facing Timer API. Its behavior depends on the `TimerHandler` implementation
/// A timer collects observations within a time window (usually things like request durations) and provides aggregated information about the data sample,
/// for example, min, max and various quantiles. It is similar to a `Recorder` but specialized for values that represent durations.
/// This is the user facing Timer API. Its behavior depends on the `TimerHandler` implementation.
public class Timer {
@usableFromInline
var handler: TimerHandler
public let label: String
public let dimensions: [(String, String)]

/// Create a new Timer.
/// Create a new `Timer`.
///
/// This initializer provides an escape hatch for situations one must use a custom factory instead of the gloabl one
/// we do not expect this API to be used in normal circumstances, so if you find yourself using it make sure its for a good reason.
/// This initializer provides an escape hatch for situations where one must use a custom factory instead of the global one.
/// We do not expect this API to be used in normal circumstances, so if you find yourself using it make sure it's for a good reason.
///
/// - parameters:
/// - label: The label for the Timer.
/// - dimensions: The dimensions for the Timer.
/// - label: The label for the `Timer`.
/// - dimensions: The dimensions for the `Timer`.
/// - handler: The custom backend.
public init(label: String, dimensions: [(String, String)], handler: TimerHandler) {
self.label = label
Expand Down Expand Up @@ -323,26 +323,26 @@ public class Timer {
}

public extension Timer {
/// Create a new Timer.
/// Create a new `Timer`.
///
/// - parameters:
/// - label: The label for the Timer.
/// - dimensions: The dimensions for the Timer.
/// - label: The label for the `Timer`.
/// - dimensions: The dimensions for the `Timer`.
convenience init(label: String, dimensions: [(String, String)] = []) {
let handler = MetricsSystem.factory.makeTimer(label: label, dimensions: dimensions)
self.init(label: label, dimensions: dimensions, handler: handler)
}

/// Signal the underlying metrics library that this timer will never be updated again.
/// In response library MAY decide to eagerly release any resources held by this timer.
/// In response the library MAY decide to eagerly release any resources held by this `Timer`.
@inlinable
func destroy() {
MetricsSystem.factory.destroyTimer(self.handler)
}
}

/// The `MetricsFactory` is the bridge between the `MetricsSystem` and the metrics backend implementation.
/// `MetricsFactory` role is to initialize concrete implementations of the various metric types:
/// `MetricsFactory`'s role is to initialize concrete implementations of the various metric types:
/// * `Counter` -> `CounterHandler`
/// * `Recorder` -> `RecorderHandler`
/// * `Timer` -> `TimerHandler`
Expand All @@ -357,7 +357,7 @@ public extension Timer {
///
/// While many metrics are bound to the entire lifetime of an application and thus never need to be destroyed eagerly,
/// some metrics have well defined unique life-cycles, and it may be beneficial to release any resources held by them
/// more eagerly than awaiting the applications termination. In such cases, a library or application should invoke
/// more eagerly than awaiting the application's termination. In such cases, a library or application should invoke
/// a metric's appropriate `destroy()` method, which in turn results in the corresponding handler that it is backed by
/// to be passed to `destroyCounter(handler:)`, `destroyRecorder(handler:)` or `destroyTimer(handler:)` where the factory
/// can decide to free any corresponding resources.
Expand All @@ -369,23 +369,23 @@ public protocol MetricsFactory {
/// Create a backing `CounterHandler`.
///
/// - parameters:
/// - label: The label for the CounterHandler.
/// - dimensions: The dimensions for the CounterHandler.
/// - label: The label for the `CounterHandler`.
/// - dimensions: The dimensions for the `CounterHandler`.
func makeCounter(label: String, dimensions: [(String, String)]) -> CounterHandler

/// Create a backing `RecorderHandler`.
///
/// - parameters:
/// - label: The label for the RecorderHandler.
/// - dimensions: The dimensions for the RecorderHandler.
/// - label: The label for the `RecorderHandler`.
/// - dimensions: The dimensions for the `RecorderHandler`.
/// - aggregate: Is data aggregation expected.
func makeRecorder(label: String, dimensions: [(String, String)], aggregate: Bool) -> RecorderHandler

/// Create a backing `TimerHandler`.
///
/// - parameters:
/// - label: The label for the TimerHandler.
/// - dimensions: The dimensions for the TimerHandler.
/// - label: The label for the `TimerHandler`.
/// - dimensions: The dimensions for the `TimerHandler`.
func makeTimer(label: String, dimensions: [(String, String)]) -> TimerHandler

/// Invoked when the corresponding `Counter`'s `destroy()` function is invoked.
Expand Down Expand Up @@ -418,7 +418,7 @@ public enum MetricsSystem {
fileprivate static var _factory: MetricsFactory = NOOPMetricsHandler.instance
fileprivate static var initialized = false

/// `bootstrap` is a one-time configuration function which globally selects the desired metrics backend
/// `bootstrap` is an one-time configuration function which globally selects the desired metrics backend
/// implementation. `bootstrap` can be called at maximum once in any given program, calling it more than once will
/// lead to undefined behaviour, most likely a crash.
///
Expand All @@ -432,7 +432,7 @@ public enum MetricsSystem {
}
}

// for our testing we want to allow multiple bootstraping
// for our testing we want to allow multiple bootstrapping
internal static func bootstrapInternal(_ factory: MetricsFactory) {
self.lock.withWriterLock {
self._factory = factory
Expand Down Expand Up @@ -524,7 +524,7 @@ public final class MultiplexMetricsHandler: MetricsFactory {
}
}

/// Ships with the metrics module, used for initial bootstraping.
/// Ships with the metrics module, used for initial bootstrapping.
public final class NOOPMetricsHandler: MetricsFactory, CounterHandler, RecorderHandler, TimerHandler {
public static let instance = NOOPMetricsHandler()

Expand Down

0 comments on commit e7de070

Please sign in to comment.