update: apply reviewers suggestions

More precise thread-safety guidance / documentation.
Fix Swift Docc checks.

Co-authored-by: Konrad `ktoso` Malawski <[email protected]>
Signed-off-by: Melissa Kilby <[email protected]>

Author: incertum

Sources/Prometheus/Docs.docc/index.md

@@ -9,10 +9,9 @@ A prometheus client library for Swift.
 #### Key Features
 
 - *Standards Compliant*: Follows Prometheus naming conventions and exposition formats, enforces base guarantees.
-- *Type Safe*: Prevents common configuration errors through Swift's type system.
-- *Thread Safe*: Operations use internal locking and conform to `Sendable`.
 - *Flexible Metric Labeling*: Supports flexible metric label structures with consistency guarantees.
-- *Swift Metrics Compatible*: Use the native Prometheus client API implemented in this library or integrate with [Swift Metrics](doc:swift-metrics).
+- *Thread Safe and Type-Safe*.
+- *Swift Metrics Compatible*: Use the native Prometheus client API implemented in this library or use [Swift Metrics](doc:swift-metrics) as a backend for this library.
 
 For general Prometheus guidance, see the [Prometheus Documentation][prometheus-docs].
 

Sources/Prometheus/Docs.docc/labels.md

@@ -2,7 +2,7 @@
 
 Create, register, update, and expose metrics for Prometheus.
 
-## Touring a Practical Example
+## Overview
 
 Create multiple collectors that are associated with a specific `PrometheusCollectorRegistry()` instance.
 
@@ -113,7 +113,7 @@ myapp_http_request_duration_seconds_count 1
 myapp_system_memory_usage_bytes 134217728.0
 ```
 
-Notice how:
+### Notice how:
 
 *Metadata Deduplication:*
 - Each metric name gets exactly one `# HELP` and `# TYPE` line (before the metric output), regardless of how many label variations exist.
@@ -137,13 +137,17 @@ Notice how:
 
 *Prometheus Compliance:*
 - Metric names, label names, and `# HELP` text are validated against Prometheus character allowlists.
-- Different label names and structures are allowed for the same metric name.
-- However, cannot mix labeled and unlabeled metrics with the same name.
+- Different label names and structures are allowed for the same metric name; however, cannot mix labeled and unlabeled metrics with the same metric name.
 - Must use consistent metric types, help text, and histogram buckets for the same metric name.
 
 *Known Limitations:*
 - Prometheus converts all metrics to floating-point types, which can cause precision loss. For example, Counters designed for `UInt64` values or Gauges capturing nanosecond timestamps will lose precision. In such cases, consider alternative frameworks or solutions.
 
+*Thread-safe through multiple mechanisms:*
+- Metric value updates are based on atomic operations.
+- Export functions like `emitToBuffer()` and `emitToString()` use internal locking and conform to Swift [Sendable](https://developer.apple.com/documentation/Swift/Sendable).
+- Lower-level export via `emit(into:)` is thread-safe due to Swift's `inout` [exclusivity](https://www.swift.org/blog/swift-5-exclusivity/) guarantees, with the compiler preventing concurrent access through warnings (Swift 5) or errors (Swift 6 [strict concurrency](https://developer.apple.com/documentation/swift/adoptingswift6) mode).
+
 ✅ *Correct Labels Usage:*
 
 ```swift
@@ -197,17 +201,11 @@ let goodCounter1 = registry.makeCounter(name: "requests_total", labels: [("metho
 let goodCounter2 = registry.makeCounter(name: "requests_total", labels: [("endpoint", "/api/users")]) // Meaningful dimensions
 ```
 
-## Thread Safety
-
-All operations are thread-safe, with the exception of the lower-level ``emit(into:)`` overload variant (compared to the thread-safe ``emitToBuffer()`` or ``emitToString()``). The client uses internal locking to ensure consistency across concurrent access and conforms to Swift's `Sendable` protocol, meaning it can be safely passed between actors and used in concurrent contexts without additional synchronization.
-
-## Additional Notes
+*Additional Notes*:
 
-Above, we demonstrated the Prometheus’s proper approach. However, you can also integrate with the `swift-metrics` ecosystem using `PrometheusMetricsFactory`.
+Above, we demonstrated the Prometheus’s proper approach. However, you can also use [Swift Metrics](doc:swift-metrics) as a backend for this library via `PrometheusMetricsFactory`.
 
-- <doc:swift-metrics>
-
-> Note: The naming between Prometheus and Swift-Metrics is a bit confusing. Swift Metrics calls a 
+> Note: The naming between Prometheus and Swift-Metrics may be confusing. Swift Metrics calls a 
 > metric's name its label and they call a metric's labels dimensions. In this article, when we 
 > refer to labels, we mean the additional properties that can be added to a metrics name.
 >
@@ -216,17 +214,18 @@ Above, we demonstrated the Prometheus’s proper approach. However, you can also
 > | swift-metrics | `label`     | `dimensions`     |
 > | Prometheus    | `name`      | `labels`         |
 
-
-## References
+### References
 
 - Prometheus [Docs - Overview][prometheus-docs]
 - Prometheus [Instrumentation Best Practices - Use Labels][prometheus-use-labels]
+- Prometheus [Naming Best Practices][prometheus-naming]
 - Prometheus [Client Library Guidelines][prometheus-client-libs]
 - Prometheus [Exporter Guidelines][prometheus-exporters]
 - Prometheus [Exposition Format][prometheus-exposition]
 
 [prometheus-docs]: https://prometheus.io/docs/introduction/overview/
 [prometheus-use-labels]: https://prometheus.io/docs/practices/instrumentation/#use-labels
+[prometheus-naming]: https://prometheus.io/docs/practices/naming/
 [prometheus-client-libs]: https://prometheus.io/docs/instrumenting/writing_clientlibs/
 [prometheus-exporters]: https://prometheus.io/docs/instrumenting/writing_exporters/
 [prometheus-exposition]: https://prometheus.io/docs/instrumenting/exposition_formats/

Sources/Prometheus/Docs.docc/swift-metrics.md

@@ -1,7 +1,6 @@
-# Integrate with Swift Metrics
+# Swift Metrics as Backend
 
-Learn how Swift Prometheus integrates with Swift Metrics – an abstract API that is widely used in 
-the swift-server ecosystem.
+Learn how to use Swift Metrics as a backend for Swift Prometheus.
 
 ## Overview
 
@@ -51,12 +50,12 @@ func main() {
 }
 ```
 
-## Modifying the Prometheus Export
+### Modifying the Prometheus Export
 
 Now that we have setup the Prometheus export, lets discuss which configuration options there are to
 modify the Swift Metrics export.
 
-### Using a specific Collector Registry as the Export Target
+#### Using a specific Collector Registry as the Export Target
 
 If you create a `PrometheusMetricsFactory()` without specifying a ``PrometheusCollectorRegistry``,
 it will use ``PrometheusMetricsFactory/defaultRegistry`` as the underlying collector registry.
@@ -78,7 +77,7 @@ factory.registry = registry
 MetricsSystem.bootstrap(factory)
 ```
 
-### Modifying Swift metrics names and labels
+#### Modifying Swift metrics names and labels
 
 When you create a ``PrometheusMetricsFactory``, you can also set the 
 ``PrometheusMetricsFactory/nameAndLabelSanitizer`` to modify the metric names and labels:
@@ -107,9 +106,9 @@ generated in a third party library.
 > Use the ``PrometheusMetricsFactory/nameAndLabelSanitizer`` to ensure this remains true metrics 
 > that are created in third party libraries. See <doc:labels> for more information about this.
 
-### Defining Buckets for Histograms
+#### Defining Buckets for Histograms
 
-#### Default buckets
+Default buckets:
 
 Swift Metric `Timer`s are backed by a Prometheus ``DurationHistogram`` and Swift Metric 
 `Recorder`s that aggregate are backed by a Prometheus ``ValueHistogram``. As a user, you can 
@@ -141,7 +140,7 @@ Timer(label: "my_timer") // will use the buckets specified in `defaultDurationHi
 Recorder(label: "my_recorder", aggregate: true) // will use the buckets specified in `defaultValueHistogramBuckets`
 ```
 
-#### Buckets by name
+Buckets by name:
 
 You can also specify the buckets by metric name:
 

Sources/Prometheus/PrometheusCollectorRegistry.swift

@@ -943,7 +943,7 @@ public final class PrometheusCollectorRegistry: Sendable {
     /// This is useful when the registry's metric composition has changed significantly and you want to
     /// optimize buffer size for the new workload.
     ///
-    /// - Note: Thread-safe. Does not affect ``emit(into:)`` calls which use external buffers
+    /// - Note: Does not affect ``emit(into:)`` calls which use external buffers
     public func resetInternalBuffer() {
         bufferBox.withLockedValue { buffer in
             // Resets capacity to 0, forcing re-calibration
@@ -958,7 +958,7 @@ public final class PrometheusCollectorRegistry: Sendable {
     /// the registry's output requirements increase.
     ///
     /// - Returns: The current buffer capacity in bytes
-    /// - Note: Thread-safe. Primarily useful for testing and monitoring buffer behavior
+    /// - Note: Primarily useful for testing and monitoring buffer behavior
     public func internalBufferCapacity() -> Int {
         return bufferBox.withLockedValue { buffer in
             buffer.capacity
@@ -972,7 +972,7 @@ public final class PrometheusCollectorRegistry: Sendable {
     /// established capacity, clearing content but preserving the initially allocated memory.
     ///
     /// - Returns: A String containing all registered metrics in Prometheus text format
-    /// - Note: Thread-safe. Use ``resetInternalBuffer()`` to force recalibration
+    /// - Note: Use ``resetInternalBuffer()`` to force recalibration
     /// - SeeAlso: ``emitToBuffer()`` for raw UTF-8 bytes, ``emit(into:)`` for custom buffer
     public func emitToString() -> String {
         return bufferBox.withLockedValue { buffer in
@@ -995,7 +995,7 @@ public final class PrometheusCollectorRegistry: Sendable {
     /// established capacity, clearing content but preserving the initially allocated memory. Returns a copy.
     ///
     /// - Returns: A copy of the UTF-8 encoded byte array containing all registered metrics
-    /// - Note: Thread-safe. Use ``resetInternalBuffer()`` to force recalibration
+    /// - Note: Use ``resetInternalBuffer()`` to force recalibration
     /// - SeeAlso: ``emitToString()`` for String output, ``emit(into:)`` for custom buffer
     public func emitToBuffer() -> [UInt8] {
         return bufferBox.withLockedValue { buffer in
@@ -1016,8 +1016,6 @@ public final class PrometheusCollectorRegistry: Sendable {
     /// performance and control but requires manual buffer lifecycle management.
     ///
     /// - Parameter buffer: The buffer to write metrics data into. Content will be appended to existing data
-    /// - Note: Not thread-safe. Caller must handle synchronization and may optimize buffer capacity for
-    ///         maximum performance by reducing reallocations
     /// - SeeAlso: ``emitToString()`` and ``emitToBuffer()`` for automatic buffer management
     public func emit(into buffer: inout [UInt8]) {
         let metrics = self.box.withLockedValue { $0 }