From 1be6323214f0e8de89796e60f72e55db5e6dd3fa Mon Sep 17 00:00:00 2001
From: Lennart Kloock <lennart.kloock@protonmail.com>
Date: Mon, 13 Jan 2025 22:00:23 +0100
Subject: [PATCH] docs(metrics): add exmaple and feature hints

---
 crates/metrics/Cargo.toml        |  4 ++++
 crates/metrics/derive/src/lib.rs | 25 ++++++++++++++++++++++++-
 crates/metrics/src/lib.rs        | 25 +++++++++++++++++++++++++
 3 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/crates/metrics/Cargo.toml b/crates/metrics/Cargo.toml
index e62b51869..e46afb762 100644
--- a/crates/metrics/Cargo.toml
+++ b/crates/metrics/Cargo.toml
@@ -26,6 +26,10 @@ default = ["prometheus"]
 tracing = ["internal-logs", "dep:tracing"]
 extended-numbers = []
 
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
 [package.metadata.xtask]
 additive-features = [
     "prometheus",
diff --git a/crates/metrics/derive/src/lib.rs b/crates/metrics/derive/src/lib.rs
index 7ce9f5ac8..35dfb7b16 100644
--- a/crates/metrics/derive/src/lib.rs
+++ b/crates/metrics/derive/src/lib.rs
@@ -1,4 +1,25 @@
-#![doc = include_str!("../README.md")]
+//! # scuffle-metrics-derive
+//!
+//! A proc-macro to derive the `#[metrics]` attribute and the
+//! `#[derive(MetricEnum)]` attribute.
+//!
+//! For more information checkout the [`scuffle-metrics`](../scuffle_metrics)
+//! crate.
+//!
+//! ## Status
+//!
+//! This crate is currently under development and is not yet stable, unit tests
+//! are not yet fully implemented.
+//!
+//! Unit tests are not yet fully implemented. Use at your own risk.
+//!
+//! ## License
+//!
+//! This project is licensed under the [MIT](./LICENSE.MIT) or
+//! [Apache-2.0](./LICENSE.Apache-2.0) license. You can choose between one of
+//! them if you use this work.
+//!
+//! `SPDX-License-Identifier: MIT OR Apache-2.0`
 
 use enum_impl::metric_enum_impl;
 use metrics_impl::metrics_impl;
@@ -39,6 +60,7 @@ mod metrics_impl;
 ///     pub fn request(kind: Kind) -> CounterU64;
 /// }
 ///
+/// // Increment the counter
 /// example::request(example::Kind::Http).incr();
 /// ```
 ///
@@ -54,6 +76,7 @@ mod metrics_impl;
 /// #[scuffle_metrics::metrics(unit = "requests")]
 /// pub fn request(kind: Kind) -> CounterU64;
 ///
+/// // Increment the counter
 /// request(Kind::Http).incr();
 /// ```
 #[proc_macro_attribute]
diff --git a/crates/metrics/src/lib.rs b/crates/metrics/src/lib.rs
index 6c961f503..b2da60051 100644
--- a/crates/metrics/src/lib.rs
+++ b/crates/metrics/src/lib.rs
@@ -3,6 +3,29 @@
 //! A wrapper around opentelemetry to provide a more ergonomic interface for
 //! creating metrics.
 //!
+//! ## Example
+//!
+//! ```rust
+//! #[scuffle_metrics::metrics]
+//! mod example {
+//!     use scuffle_metrics::{MetricEnum, collector::CounterU64};
+//!
+//!     #[derive(MetricEnum)]
+//!     pub enum Kind {
+//!         Http,
+//!         Grpc,
+//!     }
+//!
+//!     #[metrics(unit = "requests")]
+//!     pub fn request(kind: Kind) -> CounterU64;
+//! }
+//!
+//! // Increment the counter
+//! example::request(example::Kind::Http).incr();
+//! ```
+//!
+//! For details see [`metrics`].
+//!
 //! ## Status
 //!
 //! This crate is currently under development and is not yet stable.
@@ -16,8 +39,10 @@
 //! them if you use this work.
 //!
 //! `SPDX-License-Identifier: MIT OR Apache-2.0`
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 #[cfg(feature = "prometheus")]
+#[cfg_attr(docsrs, doc(cfg(feature = "prometheus")))]
 /// A copy of the opentelemetry-prometheus crate, updated to work with the
 /// latest version of opentelemetry.
 pub mod prometheus;