update: docs + usage featuring latest improvements

README.md

@@ -3,36 +3,35 @@
 [![sswg:sandbox](https://img.shields.io/badge/sswg-sandbox-yellow.svg)][SSWG-Incubation]
 [![Documentation](http://img.shields.io/badge/read_the-docs-2196f3.svg)][Documentation]
 
-A Swift client for the [Prometheus](https://github.com/prometheus/prometheus) monitoring system,
-supporting counters, gauges and histograms. Swift Prometheus 
-implements the Swift Metrics API.
+A Swift client library for [Prometheus Monitoring System](https://github.com/prometheus/prometheus).
 
-## Security
+`swift-prometheus` supports creating `Counter`s, `Gauge`s and `Histogram`s, updating metric values, and exposing their values in the Prometheus text format.
 
-Please see [SECURITY.md](SECURITY.md) for details on the security process.
+## Installation and Usage
 
-## Contributing
+Please refer to the [Documentation][Documentation] for installation, usage instructions, and implementation details including Prometheus standards compliance.
 
-All contributions are most welcome!
+For general Prometheus guidance, see [Prometheus Monitoring System][prometheus-docs].
 
-If you think of some cool new feature that should be included, please [create an issue](https://github.com/swift-server/swift-prometheus/issues/new). 
-Or, if you want to implement it yourself, [fork this repo](https://github.com/swift-server/swift-prometheus/fork) and submit a PR!
+## Security
 
-If you find a bug or have issues, please [create an issue](https://github.com/swift-server-community/SwiftPrometheus/issues/new) explaining your problems. Please include as much information as possible, so it's easier for us to reproduce (Framework, OS, Swift version, terminal output, etc.)
+Please see [SECURITY.md](SECURITY.md) for details on the security process.
 
-[Documentation]: https://swiftpackageindex.com/swift-server/swift-prometheus/documentation/prometheus
-[SSWG-Incubation]: https://www.swift.org/sswg/incubation-process.html
+## Contributing
 
+We welcome all contributions to `swift-prometheus`! For feature requests or bug reports, please [create an issue](https://github.com/swift-server/swift-prometheus/issues/new) with detailed information including Swift version, platform, and reproduction steps. To contribute code, [fork this repo](https://github.com/swift-server/swift-prometheus/fork) and submit a pull request with tests and documentation updates.
 
 ## Benchmarks
 
-Benchmarks for `swift-prometheus` are in a separate Swift Package in the `Benchmarks` subfolder of this repository.
-They use the [`package-benchmark`](https://github.com/ordo-one/package-benchmark) plugin.
-Benchmarks depends on the [`jemalloc`](https://jemalloc.net) memory allocation library, which is used by `package-benchmark` to capture memory allocation statistics.
-An installation guide can be found in the [Getting Started article](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark/gettingstarted#Installing-Prerequisites-and-Platform-Support) of `package-benchmark`.
-Afterwards you can run the benchmarks from CLI by going to the `Benchmarks` subfolder (e.g. `cd Benchmarks`) and invoking:
+Benchmarks are located in the [Benchmarks](/Benchmarks/) subfolder and use the [`package-benchmark`](https://github.com/ordo-one/package-benchmark) plugin. See the [Benchmarks Getting Started]((https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark/gettingstarted#Installing-Prerequisites-and-Platform-Support)) guide for installation instructions. Run benchmarks by navigating to Benchmarks and executing:
+
 ```
 swift package benchmark
 ```
 
-For more information please refer to `swift package benchmark --help` or the [documentation of `package-benchmark`](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark). 
+For more information please refer to `swift package benchmark --help` or the [`package-benchmark` Documentation](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark).
+
+
+[Documentation]: https://swiftpackageindex.com/swift-server/swift-prometheus/documentation/prometheus
+[prometheus-docs]: https://prometheus.io/docs/introduction/overview/
+[SSWG-Incubation]: https://www.swift.org/sswg/incubation-process.html

Sources/Prometheus/Docs.docc/index.md

@@ -1,15 +1,19 @@
 # ``Prometheus``
 
-A prometheus client library for Swift.
+A Swift client library for the Prometheus Monitoring System. 
 
 ## Overview
 
-``Prometheus`` supports creating ``Counter``s, ``Gauge``s and ``Histogram``s and exporting their
-values in the Prometheus text format.
+``Prometheus`` supports creating ``Counter``s, ``Gauge``s and ``Histogram``s, updating metric values, and exposing their values in the Prometheus text format.
 
-``Prometheus`` integrates with [Swift Metrics](doc:swift-metrics).
+#### Key Features
 
-For general advice on how to use `Prometheus` make sure to also read the [Prometheus documentation][prometheus-docs].
+- *Standards Compliant*: Follows Prometheus naming conventions and exposition formats, enforces base guarantees.
+- *Flexible Metric Labeling*: Supports flexible metric label structures with consistency guarantees.
+- *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 Monitoring System Documentation][prometheus-docs].
 
 ## Installation
 
@@ -40,41 +44,61 @@ In your Swift file you must first `import Prometheus`:
 import Prometheus
 ```
 
-Next you need to create a ``PrometheusCollectorRegistry``, which you use to create ``Counter``s, 
-``Gauge``s and ``Histogram``s.
+Create a ``PrometheusCollectorRegistry`` instance and register, for instance, a ``Counter``:
 
 ```swift
 let registry = PrometheusCollectorRegistry()
 
-let myCounter = registry.makeCounter(name: "my_counter")
-myCounter.increment()
+let httpRequestsDescriptor = MetricNameDescriptor(
+    namespace: "myapp",
+    subsystem: "http",
+    metricName: "requests",
+    unitName: "total",
+    helpText: "Total HTTP requests"
+)
+
+let httpRequestsGet = registry.makeCounter(
+    descriptor: httpRequestsDescriptor,
+    labels: [("method", "GET"), ("status", "200")]
+)
 
-let myGauge = registry.makeGauge(name: "my_gauge")
-myGauge.increment()
-myGauge.decrement()
+httpRequestsGet.increment(by: 5.0)
 ```
 
-Lastly, you can use your ``PrometheusCollectorRegistry`` to generate a Prometheus export in the 
-text representation:
+Emit all registered metrics to the Prometheus text exposition format:
 
 ```swift
-var buffer = [UInt8]()
-buffer.reserveCapacity(1024) // potentially smart moves to reduce the number of reallocations
-registry.emit(into: &buffer)
+let output = registry.emitToString()
+print(output)
+```
+
+```sh
+# HELP myapp_http_requests_total Total HTTP requests
+# TYPE myapp_http_requests_total counter
+myapp_http_requests_total{method="GET",status="200"} 5.0
+```
+
+Unregister a ``Counter``:
 
-print(String(decoding: buffer, as: Unicode.UTF8.self))
+```swift
+registry.unregisterCounter(httpRequestsGet)
 ```
 
+Explore a detailed usage guide at <doc:labels>.
+
+
 ## Topics
 
-### Getting started
+### Getting Started
 
-- <doc:swift-metrics>
 - <doc:labels>
+- <doc:swift-metrics>
+
+### Registry
+
 - ``PrometheusCollectorRegistry``
 - ``PrometheusMetricsFactory``
 
-
 ### Metrics
 
 - ``Counter``
@@ -83,4 +107,8 @@ print(String(decoding: buffer, as: Unicode.UTF8.self))
 - ``DurationHistogram``
 - ``ValueHistogram``
 
+### Configuration
+
+- ``MetricNameDescriptor``
+
 [prometheus-docs]: https://prometheus.io/docs/introduction/overview/