From 576dd79a9712fd03853deca7d67d69df7a40ed40 Mon Sep 17 00:00:00 2001
From: Joe Zhu <sha.joe.zhu@gmail.com>
Date: Fri, 11 Sep 2026 10:26:15 +0800
Subject: [PATCH] enhancing documentation

---
 R/impl_data.R   | 28 ++++++++++++++++++++++++++++
 man/pkg_data.Rd | 30 ++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)

diff --git a/R/impl_data.R b/R/impl_data.R
index c5302d9..9ee7f92 100644
--- a/R/impl_data.R
+++ b/R/impl_data.R
@@ -11,6 +11,34 @@
 #' recommended to use [`impl_data()`], which provides a high-level interface
 #' that helps make this process as simple as possible.
 #'
+#' @section Data versus metrics:
+#'
+#' Every value `r packageName()` derives about a package is *data*. A *metric*
+#' is a specially-designated subset of that data. The two terms are often used
+#' interchangeably, but the distinction matters when implementing new fields:
+#'
+#' \describe{
+#'   \item{Data}{Any information that can be derived about a package, accessed
+#'     with `pkg$field`. Data may be a raw, richly-structured or intermediate
+#'     value used only to calculate other fields (for example, the parsed
+#'     `DESCRIPTION` or a package's raw web page HTML). Data carries no
+#'     constraints on its type.}
+#'   \item{Metric}{Data that has additionally been declared a metric --
+#'     structured, regular information intended for systematic,
+#'     decision-making comparisons *across* packages (for example, a
+#'     `R CMD check` error count or a download total). To keep metrics
+#'     comparable, a metric must resolve to an *atomic* value (an
+#'     `S7` `class_atomic` subclass); declaring a non-atomic field as a
+#'     metric is an error.}
+#' }
+#'
+#' A field becomes a metric when its metadata sets `metric = TRUE`, either
+#' through the `metric` argument of [`impl_data()`]/[`impl_data_info()`] or via
+#' `impl_metric()`. This flag is what [`metrics()`] uses to decide what to
+#' surface: [`metrics()`] lists (or, given a [`pkg`], calculates) only metrics
+#' by default, while `metrics(all = TRUE)` also returns the non-metric,
+#' typically intermediate, data.
+#'
 #' @section Implementing a new metric:
 #'
 #' To implement some new data, you can use [`impl_data()`], providing, at a
diff --git a/man/pkg_data.Rd b/man/pkg_data.Rd
index b4e5f5f..6259e3d 100644
--- a/man/pkg_data.Rd
+++ b/man/pkg_data.Rd
@@ -95,6 +95,36 @@ function for a combination of data field \emph{and} package resource) and
 \item \code{impl_data_derive()}: Register a derivation function for a data field and package resource.
 
 }}
+\section{Data versus metrics}{
+
+
+Every value val.meter derives about a package is \emph{data}. A \emph{metric}
+is a specially-designated subset of that data. The two terms are often used
+interchangeably, but the distinction matters when implementing new fields:
+
+\describe{
+\item{Data}{Any information that can be derived about a package, accessed
+with \code{pkg$field}. Data may be a raw, richly-structured or intermediate
+value used only to calculate other fields (for example, the parsed
+\code{DESCRIPTION} or a package's raw web page HTML). Data carries no
+constraints on its type.}
+\item{Metric}{Data that has additionally been declared a metric --
+structured, regular information intended for systematic,
+decision-making comparisons \emph{across} packages (for example, a
+\verb{R CMD check} error count or a download total). To keep metrics
+comparable, a metric must resolve to an \emph{atomic} value (an
+\code{S7} \code{class_atomic} subclass); declaring a non-atomic field as a
+metric is an error.}
+}
+
+A field becomes a metric when its metadata sets \code{metric = TRUE}, either
+through the \code{metric} argument of \code{\link[=impl_data]{impl_data()}}/\code{\link[=impl_data_info]{impl_data_info()}} or via
+\code{impl_metric()}. This flag is what \code{\link[=metrics]{metrics()}} uses to decide what to
+surface: \code{\link[=metrics]{metrics()}} lists (or, given a \code{\link{pkg}}, calculates) only metrics
+by default, while \code{metrics(all = TRUE)} also returns the non-metric,
+typically intermediate, data.
+}
+
 \section{Implementing a new metric}{