Repository: tokio-rs/tokio
File: tokio/src/runtime/metrics/runtime.rs (Rust)

Code before:
            ///     let metrics = Handle::current().metrics();
            ///
            ///     let n = metrics.worker_park_count(0);
            ///     println!("worker 0 parked {} times", n);
            /// }
            /// ```
            pub fn worker_park_count(&self, worker: usize) -> u64 {
                self.handle
                    .inner
                    .worker_metrics(worker)
                    .park_count
                    .load(Relaxed)
            }

            /// Returns the total number of times the given worker thread has parked
            /// and unparked.
            ///
            /// The worker park/unpark count starts at zero when the runtime is created
            /// and increases by one each time the worker parks the thread waiting for
            /// new inbound events to process. This usually means the worker has processed
            /// all pending work and is currently idle. When new work becomes available,
            /// the worker is unparked and the park/unpark count is again increased by one.
            ///
            /// The counter is monotonically increasing. It is never decremented or
            /// reset to zero. An odd count means that the worker is currently parked;
            /// an even count means that the worker is active.
            ///
            /// # Arguments
            ///
            /// `worker` is the index of the worker being queried. The given value must
            /// be between 0 and `num_workers()`. The index uniquely identifies a single
            /// worker and will continue to identify the worker throughout the lifetime
            /// of the runtime instance.
            ///
            /// # Panics
            ///
            /// The method panics when `worker` represents an invalid worker, i.e. is
            /// greater than or equal to `num_workers()`.
            ///
            /// # Examples
            ///
            /// ```
            /// use tokio::runtime::Handle;
            ///
            /// #[tokio::main]
            /// async fn main() {
            ///     let metrics = Handle::current().metrics();
            ///     let n = metrics.worker_park_unpark_count(0);
            ///
            ///     println!("worker 0 parked and unparked {} times", n);
            ///

Review comment (refactor):
The paragraph starting with "The counter is monotonically increasing." is duplicated on most methods here, so putting the information about odd/even in this paragraph makes it more likely that it will be missed. I think it would be good to move the odd/even note somewhere else in this doc-comment.

Code after:
            ///     let metrics = Handle::current().metrics();
            ///
            ///     let n = metrics.worker_park_count(0);
            ///     println!("worker 0 parked {} times", n);
            /// }
            /// ```
            pub fn worker_park_count(&self, worker: usize) -> u64 {
                self.handle
                    .inner
                    .worker_metrics(worker)
                    .park_count
                    .load(Relaxed)
            }

            /// Returns the total number of times the given worker thread has parked
            /// and unparked.
            ///
            /// The worker park/unpark count starts at zero when the runtime is created
            /// and increases by one each time the worker parks the thread waiting for
            /// new inbound events to process. This usually means the worker has processed
            /// all pending work and is currently idle. When new work becomes available,
            /// the worker is unparked and the park/unpark count is again increased by one.
            ///
            /// An odd count means that the worker is currently parked.
            /// An even count means that the worker is currently active.
            ///
            /// The counter is monotonically increasing. It is never decremented or
            /// reset to zero.
            ///
            /// # Arguments
            ///
            /// `worker` is the index of the worker being queried. The given value must
            /// be between 0 and `num_workers()`. The index uniquely identifies a single
            /// worker and will continue to identify the worker throughout the lifetime
            /// of the runtime instance.
            ///
            /// # Panics
            ///
            /// The method panics when `worker` represents an invalid worker, i.e. is
            /// greater than or equal to `num_workers()`.
            ///
            /// # Examples
            ///
            /// ```
            /// use tokio::runtime::Handle;
            ///
            /// #[tokio::main]
            /// async fn main() {
            ///     let metrics = Handle::current().metrics();
            ///     let n = metrics.worker_park_unpark_count(0);
            ///