more doc fixes

metrics/src/common.rs

@@ -117,7 +117,7 @@ impl Unit {
     /// For example, the canonical label for `Seconds` would be `s`, while for `Nanoseconds`,
     /// it would be `ns`.
     ///
-    /// Not all units have a meaningful display label and so may be empty.
+    /// Not all units have a meaningful display label and so some may be empty.
     pub fn as_canonical_label(&self) -> &str {
         match self {
             Unit::Count => "",

metrics/src/key.rs

@@ -9,8 +9,8 @@ use core::{
 
 /// Inner representation of [`Key`].
 ///
-/// While [`Key`] is the type that users will interact with via [`crate::Recorder`], [`KeyData`] is
-/// responsible for the actual storage of the name and label data.
+/// While [`Key`] is the type that users will interact with via [`Recorder`][crate::Recorder`,
+/// [`KeyData`] is responsible for the actual storage of the name and label data.
 #[derive(PartialEq, Eq, Hash, Clone, Debug)]
 pub struct KeyData {
     name: SharedString,
@@ -151,18 +151,18 @@ where
 /// reference to key data initialized elsewhere.
 ///
 /// This allows for flexibility in the ways that [`KeyData`] can be passed around and reused, which
-/// allus to enable performance optimizations in specific circumstances.
+/// allows us to enable performance optimizations in specific circumstances.
 #[derive(Debug, Clone)]
 pub enum Key {
     /// A statically borrowed [`KeyData`].
     ///
-    /// If you are capable of keeping a static [`KeyData`] around, this variant can
-    /// be used to reduce allocations and improve performance.
+    /// If you are capable of keeping a static [`KeyData`] around, this variant can be used to
+    /// reduce allocations and improve performance.
     Borrowed(&'static KeyData),
     /// An owned [`KeyData`].
     ///
-    /// Useful when you need to modify a borrowed [`KeyData`] in-flight, or when
-    /// there's no way to keep around a static [`KeyData`] reference.
+    /// Useful when you need to modify a borrowed [`KeyData`] in-flight, or when there's no way to
+    /// keep around a static [`KeyData`] reference.
     Owned(KeyData),
 }
 
@@ -186,7 +186,7 @@ impl Hash for Key {
 impl Key {
     /// Converts any kind of [`Key`] into an owned [`KeyData`].
     ///
-    /// Owned variant returned as is, borrowed variant is cloned.
+    /// If this key is owned, the value is returned as is, otherwise, the contents are cloned.
     pub fn into_owned(self) -> KeyData {
         match self {
             Self::Borrowed(val) => val.clone(),

metrics/src/label.rs

@@ -3,14 +3,14 @@ use alloc::vec::Vec;
 
 /// Metadata for a metric key in the for of a key/value pair.
 ///
-/// Metrics are always defined by a name, but can optionally be assigned "labels", key/value pairs
-/// that provide metadata about the key.  Labels are typically used for differentiating the context
-/// of when an where a metric are emitted.
+/// Metrics are always defined by a name, but can optionally be assigned "labels", which are
+/// key/value pairs that provide metadata about the key.  Labels are typically used for
+/// differentiating the context of when an where a metric are emitted.
 ///
 /// For example, in a web service, you might wish to label metrics with the user ID responsible for
-/// the request currently being processed, or the request path being processed.  If a codepath
-/// branched internally -- for example, an optimized path and a fallback path -- you may wish to
-/// add a label that tracks which codepath was taken.
+/// the request currently being processed, or the request path being processed.  Another example may
+/// be that if you were running a piece o code that was turned on or off by a feature toggle, you may
+/// wish to include a label in metrics to indicate whether or not they were using the feature toggle.
 #[derive(PartialEq, Eq, Hash, Clone, Debug)]
 pub struct Label(pub(crate) SharedString, pub(crate) SharedString);
 
@@ -55,7 +55,7 @@ where
     }
 }
 
-/// A value that can be converted to [`Label`]s.
+/// A value that can be converted to a vector of [`Label`]s.
 pub trait IntoLabels {
     /// Consumes this value, turning it into a vector of [`Label`]s.
     fn into_labels(self) -> Vec<Label>;

metrics/src/lib.rs

@@ -188,10 +188,10 @@
 //! would be to utilize atomic variables for the storage.  For counters and gauges, this can be done
 //! simply by using types like [`AtomicU64`](std::sync::atomic::AtomicU64).  For histograms, this can be
 //! slightly tricky as you must hold on to all of the distinct values.  In our helper crate,
-//! [metrics-util], we've provided a type called [AtomicBucket].  For exporters that will want to get
-//! all of the current values in a batch, while clearing the bucket so that values aren't processed
-//! again, [AtomicBucket] provides a simple interface to do so, as well as optimized performance on
-//! both the insertion and read side.
+//! [`metrics-util`][metrics-util], we've provided a type called [`AtomicBucket`][AtomicBucket].  For
+//! exporters that will want to get all of the current values in a batch, while clearing the bucket so
+//! that values aren't processed again, [AtomicBucket] provides a simple interface to do so, as well as
+//! optimized performance on both the insertion and read side.
 //!
 //! ## Installing recorders
 //!