From 16993b6db2b945be349dcbce15877639f0cf16d8 Mon Sep 17 00:00:00 2001 From: Max Inden Date: Thu, 1 Sep 2022 12:09:32 +0200 Subject: [PATCH] src/lib: Add `#![deny(missing_docs)]` (#84) Enforces documentation comments on every public type. Signed-off-by: Max Inden --- src/encoding/text.rs | 12 +++++++++++- src/lib.rs | 5 +++-- src/metrics.rs | 3 +++ src/metrics/counter.rs | 5 +++++ src/metrics/exemplar.rs | 8 ++++++++ src/metrics/family.rs | 1 + src/metrics/gauge.rs | 8 ++++++++ src/metrics/histogram.rs | 4 ++++ src/metrics/info.rs | 1 + src/registry.rs | 7 +++++++ 10 files changed, 51 insertions(+), 3 deletions(-) diff --git a/src/encoding/text.rs b/src/encoding/text.rs index 57914c5..19e5c46 100644 --- a/src/encoding/text.rs +++ b/src/encoding/text.rs @@ -40,6 +40,8 @@ use std::ops::Deref; pub use prometheus_client_derive_text_encode::*; +/// Encode the metrics registered with the provided [`Registry`] into the +/// provided [`Write`]r using the OpenMetrics text format. pub fn encode(writer: &mut W, registry: &Registry) -> Result<(), std::io::Error> where W: Write, @@ -92,7 +94,9 @@ where Ok(()) } +/// OpenMetrics text encoding for a value. pub trait Encode { + /// Encode to OpenMetrics text encoding. fn encode(&self, writer: &mut dyn Write) -> Result<(), std::io::Error>; } @@ -304,6 +308,7 @@ impl<'a, 'b> Encoder<'a, 'b> { } } +/// Used to encode an OpenMetrics Histogram bucket. #[allow(missing_debug_implementations)] #[must_use] pub struct BucketEncoder<'a> { @@ -344,6 +349,7 @@ impl<'a> BucketEncoder<'a> { } } +/// Used to encode an OpenMetrics metric value. #[allow(missing_debug_implementations)] #[must_use] pub struct ValueEncoder<'a> { @@ -362,6 +368,7 @@ impl<'a> ValueEncoder<'a> { } } +/// Used to encode an OpenMetrics Exemplar. #[allow(missing_debug_implementations)] #[must_use] pub struct ExemplarEncoder<'a> { @@ -389,10 +396,12 @@ impl<'a> ExemplarEncoder<'a> { } } -/// Trait implemented by each metric type, e.g. [`Counter`], to implement its encoding. +/// Trait implemented by each metric type, e.g. [`Counter`], to implement its encoding in the OpenMetric text format. pub trait EncodeMetric { + /// Encode the given instance in the OpenMetrics text encoding. fn encode(&self, encoder: Encoder) -> Result<(), std::io::Error>; + /// The OpenMetrics metric type of the instance. // One can not use [`TypedMetric`] directly, as associated constants are not // object safe and thus can not be used with dynamic dispatching. fn metric_type(&self) -> MetricType; @@ -408,6 +417,7 @@ impl EncodeMetric for Box { } } +/// Trait combining [`EncodeMetric`], [`Send`] and [`Sync`]. pub trait SendSyncEncodeMetric: EncodeMetric + Send + Sync {} impl SendSyncEncodeMetric for T {} diff --git a/src/lib.rs b/src/lib.rs index b5edaac..dd9b654 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,6 +1,7 @@ -#![forbid(unsafe_code)] -#![deny(unused)] #![deny(dead_code)] +#![deny(missing_docs)] +#![deny(unused)] +#![forbid(unsafe_code)] #![warn(missing_debug_implementations)] //! Client library implementation of the [Open Metrics diff --git a/src/metrics.rs b/src/metrics.rs index e09504e..647fa5c 100644 --- a/src/metrics.rs +++ b/src/metrics.rs @@ -9,10 +9,13 @@ pub mod info; /// A metric that is aware of its Open Metrics metric type. pub trait TypedMetric { + /// The OpenMetrics metric type. const TYPE: MetricType = MetricType::Unknown; } +/// OpenMetrics metric type. #[derive(Clone, Copy, Debug)] +#[allow(missing_docs)] pub enum MetricType { Counter, Gauge, diff --git a/src/metrics/counter.rs b/src/metrics/counter.rs index 689723d..bd886c5 100644 --- a/src/metrics/counter.rs +++ b/src/metrics/counter.rs @@ -45,6 +45,7 @@ pub struct Counter { phantom: PhantomData, } +/// Open Metrics [`Counter`] to measure discrete events. #[cfg(any(target_arch = "mips", target_arch = "powerpc"))] #[derive(Debug)] pub struct Counter { @@ -99,11 +100,15 @@ impl> Counter { } } +/// Atomic operations for a [`Counter`] value store. pub trait Atomic { + /// Increase the value by `1`. fn inc(&self) -> N; + /// Increase the value. fn inc_by(&self, v: N) -> N; + /// Get the the value. fn get(&self) -> N; } diff --git a/src/metrics/exemplar.rs b/src/metrics/exemplar.rs index b08fdc3..8446200 100644 --- a/src/metrics/exemplar.rs +++ b/src/metrics/exemplar.rs @@ -12,6 +12,7 @@ use std::sync::atomic::AtomicU32; use std::sync::atomic::AtomicU64; use std::sync::Arc; +/// An OpenMetrics exemplar. #[derive(Debug)] pub struct Exemplar { pub(crate) label_set: S, @@ -36,6 +37,8 @@ pub struct CounterWithExemplar { pub(crate) inner: Arc>>, } +/// Open Metrics [`Counter`] with an [`Exemplar`] to both measure discrete +/// events and track references to data outside of the metric set. #[cfg(any(target_arch = "mips", target_arch = "powerpc"))] #[derive(Debug)] pub struct CounterWithExemplar { @@ -50,6 +53,7 @@ impl Clone for CounterWithExemplar { } } +/// An OpenMetrics [`Counter`] in combination with an OpenMetrics [`Exemplar`]. #[derive(Debug)] pub struct CounterWithExemplarInner { pub(crate) exemplar: Option>, @@ -132,6 +136,7 @@ impl Clone for HistogramWithExemplars { } } +/// An OpenMetrics [`Histogram`] in combination with an OpenMetrics [`Exemplar`]. #[derive(Debug)] pub struct HistogramWithExemplarsInner { pub(crate) exemplars: HashMap>, @@ -139,6 +144,7 @@ pub struct HistogramWithExemplarsInner { } impl HistogramWithExemplars { + /// Create a new [`HistogramWithExemplars`]. pub fn new(buckets: impl Iterator) -> Self { Self { inner: Arc::new(RwLock::new(HistogramWithExemplarsInner { @@ -148,6 +154,8 @@ impl HistogramWithExemplars { } } + /// Observe the given value, optionally providing a label set and thus + /// setting the [`Exemplar`] value. pub fn observe(&self, v: f64, label_set: Option) { let mut inner = self.inner.write(); let bucket = inner.histogram.observe_and_bucket(v); diff --git a/src/metrics/family.rs b/src/metrics/family.rs index fb5dbeb..b5f54a6 100644 --- a/src/metrics/family.rs +++ b/src/metrics/family.rs @@ -136,6 +136,7 @@ pub struct Family M> { /// let metric = Family::<(), Histogram, CustomBuilder>::new_with_constructor(custom_builder); /// ``` pub trait MetricConstructor { + /// Create a new instance of the metric type. fn new_metric(&self) -> M; } diff --git a/src/metrics/gauge.rs b/src/metrics/gauge.rs index a8e4114..ad49d81 100644 --- a/src/metrics/gauge.rs +++ b/src/metrics/gauge.rs @@ -45,6 +45,7 @@ pub struct Gauge { phantom: PhantomData, } +/// Open Metrics [`Gauge`] to record current measurements. #[cfg(any(target_arch = "mips", target_arch = "powerpc"))] #[derive(Debug)] pub struct Gauge { @@ -110,17 +111,24 @@ impl> Gauge { } } +/// Atomic operations for a [`Gauge`] value store. pub trait Atomic { + /// Increase the value by `1`. fn inc(&self) -> N; + /// Increase the value. fn inc_by(&self, v: N) -> N; + /// Decrease the value by `1`. fn dec(&self) -> N; + /// Decrease the value. fn dec_by(&self, v: N) -> N; + /// Set the value. fn set(&self, v: N) -> N; + /// Get the value. fn get(&self) -> N; } diff --git a/src/metrics/histogram.rs b/src/metrics/histogram.rs index e641d76..5922a28 100644 --- a/src/metrics/histogram.rs +++ b/src/metrics/histogram.rs @@ -54,6 +54,7 @@ pub(crate) struct Inner { } impl Histogram { + /// Create a new [`Histogram`]. pub fn new(buckets: impl Iterator) -> Self { Self { inner: Arc::new(RwLock::new(Inner { @@ -68,6 +69,7 @@ impl Histogram { } } + /// Observe the given value. pub fn observe(&self, v: f64) { self.observe_and_bucket(v); } @@ -110,6 +112,7 @@ impl TypedMetric for Histogram { const TYPE: MetricType = MetricType::Histogram; } +/// Exponential bucket distribution. pub fn exponential_buckets(start: f64, factor: f64, length: u16) -> impl Iterator { iter::repeat(()) .enumerate() @@ -117,6 +120,7 @@ pub fn exponential_buckets(start: f64, factor: f64, length: u16) -> impl Iterato .take(length.into()) } +/// Linear bucket distribution. pub fn linear_buckets(start: f64, width: f64, length: u16) -> impl Iterator { iter::repeat(()) .enumerate() diff --git a/src/metrics/info.rs b/src/metrics/info.rs index 8457207..6201cdf 100644 --- a/src/metrics/info.rs +++ b/src/metrics/info.rs @@ -16,6 +16,7 @@ use crate::metrics::{MetricType, TypedMetric}; pub struct Info(pub(crate) S); impl Info { + /// Create [`Info`] metric with the provided label set. pub fn new(label_set: S) -> Self { Self(label_set) } diff --git a/src/registry.rs b/src/registry.rs index dcb0192..8760312 100644 --- a/src/registry.rs +++ b/src/registry.rs @@ -238,6 +238,7 @@ impl Registry { .expect("sub_registries not to be empty.") } + /// [`Iterator`] over all metrics registered with the [`Registry`]. pub fn iter(&self) -> RegistryIterator { let metrics = self.metrics.iter(); let sub_registries = self.sub_registries.iter(); @@ -297,6 +298,7 @@ impl From for String { } } +/// OpenMetrics metric descriptor. #[derive(Debug)] pub struct Descriptor { name: String, @@ -306,18 +308,22 @@ pub struct Descriptor { } impl Descriptor { + /// Returns the name of the OpenMetrics metric [`Descriptor`]. pub fn name(&self) -> &str { &self.name } + /// Returns the help text of the OpenMetrics metric [`Descriptor`]. pub fn help(&self) -> &str { &self.help } + /// Returns the unit of the OpenMetrics metric [`Descriptor`]. pub fn unit(&self) -> &Option { &self.unit } + /// Returns the label set of the OpenMetrics metric [`Descriptor`]. pub fn labels(&self) -> &[(Cow<'static, str>, Cow<'static, str>)] { &self.labels } @@ -327,6 +333,7 @@ impl Descriptor { /// /// See [`Unit::Other`] to specify alternative units. #[derive(Debug)] +#[allow(missing_docs)] pub enum Unit { Amperes, Bytes,