This is an automated email from the ASF dual-hosted git repository.

tisonkun pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datasketches-rust.git


The following commit(s) were added to refs/heads/main by this push:
     new 3b50fe2  docs(density): align public API documentation with crate 
conventions (#381)
3b50fe2 is described below

commit 3b50fe2213ae1994e18e4f7204b6967b2f71500e
Author: tison <[email protected]>
AuthorDate: Tue Nov 17 15:42:05 2026 +0800

    docs(density): align public API documentation with crate conventions (#381)
---
 datasketches/src/density/iter.rs   |  4 +--
 datasketches/src/density/kernel.rs |  4 ---
 datasketches/src/density/mod.rs    |  5 ++++
 datasketches/src/density/sketch.rs | 51 ++++++++++++++++++++------------------
 datasketches/src/density/value.rs  |  2 +-
 5 files changed, 35 insertions(+), 31 deletions(-)

diff --git a/datasketches/src/density/iter.rs b/datasketches/src/density/iter.rs
index 9018882..18d0642 100644
--- a/datasketches/src/density/iter.rs
+++ b/datasketches/src/density/iter.rs
@@ -24,8 +24,8 @@ use crate::density::sketch::Level;
 /// Iterator over `(point, weight)` pairs retained in a
 /// [`DensitySketch`](crate::density::DensitySketch).
 ///
-/// Each yielded entry borrows the point slice directly from the sketch 
together with its level
-/// weight `1_u64 << height`.
+/// Points are borrowed from the sketch without allocation, paired with their 
coreset weight (`1`
+/// before compaction, doubling with each compaction level).
 #[must_use = "iterators are lazy and do nothing unless consumed"]
 pub struct DensitySketchIter<'a, T> {
     levels: &'a [Level<T>],
diff --git a/datasketches/src/density/kernel.rs 
b/datasketches/src/density/kernel.rs
index 426f6d9..af74737 100644
--- a/datasketches/src/density/kernel.rs
+++ b/datasketches/src/density/kernel.rs
@@ -29,10 +29,6 @@ pub trait Kernel<T>: PartialEq {
 }
 
 /// Standard unscaled Gaussian (RBF) kernel: `exp(-sum_i (a_i - b_i)^2)`.
-///
-/// # Panics
-///
-/// [`Kernel::evaluate`] panics if `a.len() != b.len()`.
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct GaussianKernel;
 
diff --git a/datasketches/src/density/mod.rs b/datasketches/src/density/mod.rs
index 5c653ee..1a73876 100644
--- a/datasketches/src/density/mod.rs
+++ b/datasketches/src/density/mod.rs
@@ -22,6 +22,11 @@
 //! based on [Discrepancy, Coresets, and Sketches in Machine 
Learning](https://proceedings.mlr.press/v99/karnin19a/karnin19a.pdf)
 //! by Zohar Karnin and Edo Liberty.
 //!
+//! Point coordinates use `f32` or `f64` ([`DensityValue`]). 
[`DensitySketch::new`] uses the
+//! default [`GaussianKernel`]; supply a custom [`Kernel`] with 
[`DensitySketch::with_kernel`]. The
+//! binary serialization format supports cross-language interchange when both 
sides use the same
+//! coordinate type and kernel.
+//!
 //! # Examples
 //!
 //! ```
diff --git a/datasketches/src/density/sketch.rs 
b/datasketches/src/density/sketch.rs
index 8dbd3d2..9b07fe5 100644
--- a/datasketches/src/density/sketch.rs
+++ b/datasketches/src/density/sketch.rs
@@ -42,8 +42,7 @@ impl<T> Default for Level<T> {
 
 /// Streaming kernel density estimation sketch over `dim`-dimensional vectors.
 ///
-/// Builds a weighted coreset of finite floating-point points by compacting 
full levels with a
-/// greedy discrepancy-halving rule. See the [module 
documentation](crate::density) for background.
+/// See the [density module documentation](crate::density) for background and 
usage.
 #[derive(Clone)]
 pub struct DensitySketch<T, K = GaussianKernel> {
     k: u16,
@@ -96,14 +95,15 @@ impl<T: DensityValue> DensitySketch<T, GaussianKernel> {
         Self::make_with_kernel(k, dim, GaussianKernel)
     }
 
-    /// Deserializes a sketch using [`GaussianKernel`] from the DataSketches 
binary format.
+    /// Deserializes a sketch from bytes using [`GaussianKernel`].
     ///
-    /// Accepts images serialized by `datasketches-cpp`'s `density_sketch`. Use
-    /// [`Self::deserialize_with_kernel`] for sketches built with a custom 
[`Kernel`].
+    /// Also accepts data serialized by other DataSketches implementations 
when both sides use the
+    /// same coordinate type and [`GaussianKernel`]. Use 
[`Self::deserialize_with_kernel`] for
+    /// sketches built with a custom [`Kernel`].
     ///
     /// # Errors
     ///
-    /// Returns [`InvalidData`](crate::error::ErrorKind::InvalidData) if the 
input is truncated,
+    /// Returns [`InvalidData`](crate::error::ErrorKind::InvalidData) if the 
image is truncated,
     /// malformed, or contains non-finite coordinates.
     ///
     /// # Examples
@@ -165,7 +165,7 @@ impl<T: DensityValue, K> DensitySketch<T, K> {
         &self.kernel
     }
 
-    /// Returns the total stream weight (number of observed points).
+    /// Returns the total stream weight.
     pub fn total_weight(&self) -> u64 {
         self.n
     }
@@ -175,7 +175,7 @@ impl<T: DensityValue, K> DensitySketch<T, K> {
         self.n == 0
     }
 
-    /// Returns `true` if the sketch is in estimation mode (compaction has 
occurred).
+    /// Returns `true` if the sketch is in estimation mode.
     pub fn is_estimation_mode(&self) -> bool {
         // Compaction normally creates higher levels (`levels.len() > 1`), 
while `datasketches-cpp`
         // round-trips can strip trailing empty levels and leave a single 
compacted level with
@@ -184,12 +184,12 @@ impl<T: DensityValue, K> DensitySketch<T, K> {
             || u64::try_from(self.num_retained).is_ok_and(|retained| retained 
< self.n)
     }
 
-    /// Returns the number of points currently retained across all levels.
+    /// Returns the number of retained points.
     pub fn num_retained(&self) -> usize {
         self.num_retained
     }
 
-    /// Returns an implementation-dependent estimate of heap memory usage in 
bytes.
+    /// Returns an estimate of the sketch's memory usage in bytes.
     pub fn estimated_size(&self) -> usize {
         self.levels.capacity() * size_of::<Level<T>>()
             + self
@@ -199,7 +199,7 @@ impl<T: DensityValue, K> DensitySketch<T, K> {
                 .sum::<usize>()
     }
 
-    /// Resets the sketch to the empty state while preserving `k`, `dim`, and 
`kernel`.
+    /// Resets the sketch to its empty state while retaining `k`, `dim`, and 
`kernel`.
     pub fn reset(&mut self) {
         self.n = 0;
         self.num_retained = 0;
@@ -207,7 +207,7 @@ impl<T: DensityValue, K> DensitySketch<T, K> {
         self.levels[0].coords.clear();
     }
 
-    /// Returns an iterator over retained `(point, weight)` entries across all 
levels.
+    /// Returns an iterator over retained `(point, weight)` pairs.
     pub fn iter(&self) -> DensitySketchIter<'_, T> {
         DensitySketchIter::new(&self.levels, self.dim as usize, 
self.num_retained)
     }
@@ -290,7 +290,7 @@ impl<T: DensityValue, K: Kernel<T>> DensitySketch<T, K> {
     ///
     /// # Panics
     ///
-    /// Panics without modifying the sketch if the total stream weight would 
exceed `u64::MAX`, or
+    /// Panics without modifying the sketch if the total stream weight would 
exceed [`u64::MAX`], or
     /// if compaction reaches the maximum supported level count (`64`).
     ///
     /// # Examples
@@ -318,12 +318,14 @@ impl<T: DensityValue, K: Kernel<T>> DensitySketch<T, K> {
 
     /// Merges another sketch into `self`.
     ///
+    /// Retains `self.k()`, even if `other` uses a different value.
+    ///
     /// # Errors
     ///
     /// Returns [`InvalidArgument`](crate::error::ErrorKind::InvalidArgument) 
without modifying
     /// `self` if `self.dim() != other.dim()`, if `self.kernel() != 
other.kernel()`, if the
-    /// combined stream weight would exceed `u64::MAX`, or if the combined 
retained count would
-    /// exceed `usize::MAX`.
+    /// combined stream weight would exceed [`u64::MAX`], or if the combined 
retained count would
+    /// exceed [`usize::MAX`].
     ///
     /// # Panics
     ///
@@ -396,13 +398,13 @@ impl<T: DensityValue, K: Kernel<T>> DensitySketch<T, K> {
 
     /// Estimates the normalized kernel density at `point`.
     ///
-    /// Validates `point` before checking emptiness. Returns `Ok(None)` when 
the sketch is empty.
+    /// Returns `Ok(None)` if the sketch is empty.
     ///
     /// # Errors
     ///
     /// Returns [`InvalidArgument`](crate::error::ErrorKind::InvalidArgument) 
if
-    /// `point.len() != self.dim() as usize` or any coordinate is non-finite, 
even when the sketch
-    /// is empty.
+    /// `point.len() != self.dim() as usize` or any coordinate is non-finite, 
even if the sketch is
+    /// empty.
     ///
     /// # Examples
     ///
@@ -438,21 +440,22 @@ impl<T: DensityValue, K: Kernel<T>> DensitySketch<T, K> {
         Ok(Some(weighted_sum / (self.n as f64)))
     }
 
-    /// Serializes the sketch into the DataSketches binary format.
+    /// Serializes this sketch to bytes.
     ///
-    /// The encoded bytes are compatible with `datasketches-cpp`'s 
`density_sketch` and do not
-    /// include kernel configuration; see [`Self::deserialize_with_kernel`].
+    /// The serialized data can be read by other DataSketches implementations 
when both sides use
+    /// the same coordinate type and kernel. Kernel configuration is not 
stored in the image.
     pub fn serialize(&self) -> Vec<u8> {
         serialize_sketch(self)
     }
 
-    /// Deserializes a sketch with a custom `kernel` from the DataSketches 
binary format.
+    /// Deserializes a sketch from bytes using `kernel`.
     ///
-    /// Supply a `kernel` equivalent to the one used when building the 
serialized sketch.
+    /// Also accepts data serialized by other DataSketches implementations 
when both sides use the
+    /// same coordinate type and an equivalent `kernel`.
     ///
     /// # Errors
     ///
-    /// Returns [`InvalidData`](crate::error::ErrorKind::InvalidData) if the 
input is truncated,
+    /// Returns [`InvalidData`](crate::error::ErrorKind::InvalidData) if the 
image is truncated,
     /// malformed, or contains non-finite coordinates.
     ///
     /// # Examples
diff --git a/datasketches/src/density/value.rs 
b/datasketches/src/density/value.rs
index e3135c4..60536b8 100644
--- a/datasketches/src/density/value.rs
+++ b/datasketches/src/density/value.rs
@@ -18,7 +18,7 @@
 use crate::codec::SketchBytes;
 use crate::codec::SketchSlice;
 
-/// Sealed marker trait identifying coordinate value types supported by
+/// Marker trait identifying the coordinate types supported by
 /// [`DensitySketch`](crate::density::DensitySketch).
 ///
 /// Implemented for `f32` and `f64`.


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to