docs: standardize public API documentation style

CONTRIBUTING.md

@@ -60,6 +60,12 @@ Lint:
 cargo x lint
 ```
 
+## Public API documentation
+
+- Describe types with noun phrases and API behavior with third-person present-tense verbs such as `Creates`, `Updates`, and `Returns`.
+- End summary sentences with punctuation, and format Rust identifiers, literals, and numeric ranges as inline code.
+- Put contract sections and compatibility notes before examples. When applicable, order sections as `# Errors`, `# Panics`, and `# Examples`. Include only sections that describe an actual contract.
+
 ## Integration test layout
 
 Integration tests for the `datasketches` crate live under `datasketches/tests` and use two entry-point patterns.

datasketches/src/bloom/builder.rs

@@ -52,12 +52,12 @@ impl BloomFilterBuilder {
     ///
     /// # Arguments
     ///
-    /// * `max_items`: Maximum expected number of distinct items
-    /// * `fpp`: Target false positive probability (e.g., 0.01 for 1%)
+    /// * `max_items`: Maximum expected number of distinct items.
+    /// * `fpp`: Target false positive probability (for example, `0.01` for `1%`).
     ///
     /// # Panics
     ///
-    /// Panics if `max_items` is 0 or `fpp` is not in (0.0, 1.0].
+    /// Panics if `max_items` is `0` or `fpp` is outside `(0.0, 1.0]`.
     ///
     /// # Examples
     ///
@@ -96,14 +96,14 @@ impl BloomFilterBuilder {
     ///
     /// # Arguments
     ///
-    /// * `num_bits`: Total number of bits in the filter
-    /// * `num_hashes`: Number of hash functions to use
+    /// * `num_bits`: Total number of bits in the filter.
+    /// * `num_hashes`: Number of hash functions to use.
     ///
     /// # Panics
     ///
     /// Panics if any of:
-    /// * `num_bits` < [`Self::MIN_NUM_BITS`] or `num_bits` > [`Self::MAX_NUM_BITS`]
-    /// * `num_hashes` < [`Self::MIN_NUM_HASHES`] or `num_hashes` > [`Self::MAX_NUM_HASHES`]
+    /// * `num_bits < Self::MIN_NUM_BITS` or `num_bits > Self::MAX_NUM_BITS`.
+    /// * `num_hashes < Self::MIN_NUM_HASHES` or `num_hashes > Self::MAX_NUM_HASHES`.
     ///
     /// # Examples
     ///

datasketches/src/bloom/sketch.rs

@@ -52,11 +52,10 @@ pub struct BloomFilter {
 }
 
 impl BloomFilter {
-    /// Tests whether an item is possibly in the set.
+    /// Returns `true` if an item is possibly in the set.
     ///
-    /// Returns:
-    /// * `true`: Item was **possibly** inserted (or false positive)
-    /// * `false`: Item was **definitely not** inserted
+    /// A `false` result means the item was definitely not inserted; a `true` result may be a false
+    /// positive.
     ///
     /// # Examples
     ///
@@ -78,9 +77,8 @@ impl BloomFilter {
         self.check_bits(h0, h1)
     }
 
-    /// Tests and inserts an item in a single operation.
+    /// Returns `true` if an item was possibly present before inserting it.
     ///
-    /// Returns whether the item was possibly already in the set before insertion.
     /// This is more efficient than calling `contains()` then `insert()` separately.
     ///
     /// # Examples
@@ -294,7 +292,7 @@ impl BloomFilter {
         self.num_bits_set as f64 / self.capacity() as f64
     }
 
-    /// Estimates the current false positive probability.
+    /// Returns the estimated current false positive probability.
     ///
     /// Uses the approximation: `load_factor^k`
     /// where:
@@ -312,7 +310,7 @@ impl BloomFilter {
         load.powf(k)
     }
 
-    /// Checks if two filters are compatible for merging.
+    /// Returns `true` if two filters are compatible for merging.
     ///
     /// Filters are compatible if they have the same:
     /// * Capacity (number of bits)
@@ -389,9 +387,9 @@ impl BloomFilter {
     /// # Errors
     ///
     /// Returns an error if:
-    /// * The data is truncated or corrupted
-    /// * The family ID doesn't match (not a Bloom filter)
-    /// * The serial version is unsupported
+    /// * The data is truncated or corrupted.
+    /// * The family ID does not identify a Bloom filter.
+    /// * The serial version is unsupported.
     ///
     /// # Examples
     ///
@@ -572,7 +570,7 @@ impl BloomFilter {
         }
     }
 
-    /// Returns the estimated size of the filter in bytes
+    /// Returns the estimated size of the filter in bytes.
     pub fn estimated_size(&self) -> usize {
         size_of::<Self>() + self.bit_array.len() * size_of::<u64>()
     }

datasketches/src/codec/encode.rs

@@ -21,14 +21,14 @@ pub struct SketchBytes {
 }
 
 impl SketchBytes {
-    /// Constructs an empty `SketchBytes` with at least the specified capacity.
+    /// Creates an empty `SketchBytes` with at least the specified capacity.
     pub fn with_capacity(capacity: usize) -> Self {
         Self {
             bytes: Vec::with_capacity(capacity),
         }
     }
 
-    /// Consumes the `SketchBytes` and returns the underlying `Vec<u8>`.
+    /// Returns the underlying `Vec<u8>`, consuming the `SketchBytes`.
     pub fn into_bytes(self) -> Vec<u8> {
         self.bytes
     }

datasketches/src/common/num_std_dev.rs

@@ -28,7 +28,7 @@ static DELTA_OF_NUM_STD_DEVS: [f64; 4] = [
     0.0013498126861731796, // = 0.5 (1 + erf((-3/sqrt(2))))
 ];
 
-/// Number of standard deviations for confidence bounds
+/// Number of standard deviations for confidence bounds.
 ///
 /// This enum specifies the number of standard deviations to use when computing
 /// upper and lower bounds for cardinality estimates. Higher values provide wider
@@ -37,21 +37,21 @@ static DELTA_OF_NUM_STD_DEVS: [f64; 4] = [
 #[repr(u8)]
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum NumStdDev {
-    /// One standard deviation (\~68% confidence interval)
+    /// One standard deviation (\~68% confidence interval).
     One = 1,
-    /// Two standard deviations (\~95% confidence interval)
+    /// Two standard deviations (\~95% confidence interval).
     Two = 2,
-    /// Three standard deviations (\~99.7% confidence interval)
+    /// Three standard deviations (\~99.7% confidence interval).
     Three = 3,
 }
 
 impl NumStdDev {
-    /// Returns the tail probability (delta) for this confidence level
+    /// Returns the tail probability (delta) for this confidence level.
     pub const fn tail_probability(&self) -> f64 {
         DELTA_OF_NUM_STD_DEVS[*self as usize]
     }
 
-    /// Returns the number of standard deviations as an `u8`.
+    /// Returns the number of standard deviations as a `u8`.
     pub const fn as_u8(&self) -> u8 {
         *self as u8
     }

datasketches/src/common/resize.rs

@@ -15,23 +15,22 @@
 // specific language governing permissions and limitations
 // under the License.
 
-/// For the Families that accept this configuration parameter, it controls the size multiple that
-/// affects how fast the internal cache grows, when more space is required.
+/// Controls internal cache growth for sketch families that support resizing.
 ///
-/// For Theta Sketches, the Resize Factor is a dynamic, speed performance vs. memory size tradeoff.
-/// The sketches created on-heap and configured with a Resize Factor of > X1 start out with an
-/// internal hash table size that is the smallest submultiple of the target Nominal Entries
+/// For Theta sketches, the resize factor provides a dynamic trade-off between update speed and
+/// memory use. Sketches configured with a resize factor greater than `X1` start with an internal
+/// hash table size that is the smallest submultiple of the target nominal entries
 /// and larger than the minimum required hash table size for that sketch.
 ///
-/// When the sketch needs to be resized larger, then the Resize Factor is used as a multiplier of
+/// When the sketch needs to grow, the resize factor is used as a multiplier for
 /// the current sketch cache array size.
 ///
-/// "X1" means no resizing is allowed and the sketch will be initialized at full size.
+/// `X1` means no resizing is allowed and the sketch will be initialized at full size.
 ///
-/// "X2" means the internal cache will start very small and double in size until the target size is
+/// `X2` means the internal cache will start very small and double in size until the target size is
 /// reached.
 ///
-/// Similarly, "X4" is a factor of 4 and "X8" is a factor of 8.
+/// Similarly, `X4` is a factor of `4` and `X8` is a factor of `8`.
 ///
 /// # Examples
 ///
@@ -44,18 +43,18 @@
 /// ```
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ResizeFactor {
-    /// Do not resize. Sketch will be configured to full size.
+    /// Does not resize; configures the sketch at full size.
     X1,
-    /// Resize by factor of 2
+    /// Resizes by a factor of `2`.
     X2,
-    /// Resize by factor of 4
+    /// Resizes by a factor of `4`.
     X4,
-    /// Resize by factor of 8
+    /// Resizes by a factor of `8`.
     X8,
 }
 
 impl ResizeFactor {
-    /// Returns the Log-base 2 of the Resize Factor
+    /// Returns the base-2 logarithm of the resize factor.
     pub fn lg_value(self) -> u8 {
         match self {
             ResizeFactor::X1 => 0,

datasketches/src/countmin/sketch.rs

@@ -59,7 +59,7 @@ impl<T: CountMinValue> CountMinSketch<T> {
     ///
     /// # Panics
     ///
-    /// Panics if `num_hashes` is 0, `num_buckets` is less than 3, or the
+    /// Panics if `num_hashes` is `0`, `num_buckets` is less than `3`, or the
     /// total table size exceeds the supported limit.
     ///
     /// # Examples
@@ -79,10 +79,10 @@ impl<T: CountMinValue> CountMinSketch<T> {
     /// # Panics
     ///
     /// Panics if any of:
-    /// * `num_hashes` is 0
-    /// * `num_buckets` is less than 3
-    /// * the total table size exceeds the supported limit
-    /// * the computed seed hash is zero
+    /// * `num_hashes` is `0`.
+    /// * `num_buckets` is less than `3`.
+    /// * The total table size exceeds the supported limit.
+    /// * The computed seed hash is zero.
     ///
     /// # Examples
     ///
@@ -122,7 +122,7 @@ impl<T: CountMinValue> CountMinSketch<T> {
         std::f64::consts::E / self.num_buckets as f64
     }
 
-    /// Returns true if the sketch has not seen any updates.
+    /// Returns `true` if the sketch has not seen any updates.
     pub fn is_empty(&self) -> bool {
         self.total_weight == T::ZERO
     }
@@ -455,6 +455,10 @@ impl<T: UnsignedCountMinValue> CountMinSketch<T> {
     /// Values are truncated toward zero after multiplication; choose `decay` in `(0, 1]`.
     /// The total weight is scaled by the same factor to keep bounds consistent.
     ///
+    /// # Panics
+    ///
+    /// Panics if `decay` is not finite or is outside `(0, 1]`.
+    ///
     /// # Examples
     ///
     /// ```
@@ -465,10 +469,6 @@ impl<T: UnsignedCountMinValue> CountMinSketch<T> {
     /// sketch.decay(0.5);
     /// assert!(sketch.estimate("apple") >= 1);
     /// ```
-    ///
-    /// # Panics
-    ///
-    /// Panics if `decay` is not finite or is outside `(0, 1]`.
     pub fn decay(&mut self, decay: f64) {
         assert!(decay > 0.0 && decay <= 1.0, "decay must be within (0, 1]");
         for c in &mut self.counts {

datasketches/src/cpc/sketch.rs

@@ -128,7 +128,7 @@ impl CpcSketch {
         }
     }
 
-    /// Return the parameter lg_k.
+    /// Returns the configured `lg_k`.
     pub fn lg_k(&self) -> u8 {
         self.lg_k
     }
@@ -165,12 +165,12 @@ impl CpcSketch {
         )
     }
 
-    /// Returns true if the sketch is empty.
+    /// Returns `true` if the sketch is empty.
     pub fn is_empty(&self) -> bool {
         self.num_coupons == 0
     }
 
-    /// Update the sketch with a hashable value.
+    /// Updates the sketch with a hashable value.
     ///
     /// You may use [`hash::value`](crate::hash::value) wrappers when another DataSketches
     /// implementation requires a specific value hashing strategy.
@@ -452,7 +452,7 @@ impl CpcSketch {
         matrix
     }
 
-    /// Returns the estimated size of the sketch in bytes
+    /// Returns the estimated size of the sketch in bytes.
     pub fn estimated_size(&self) -> usize {
         let heap_size = self.sliding_window.capacity()
             + self
@@ -466,7 +466,7 @@ impl CpcSketch {
 }
 
 impl CpcSketch {
-    /// Serializes this CpcSketch to bytes.
+    /// Serializes this `CpcSketch` to bytes.
     pub fn serialize(&self) -> Vec<u8> {
         let mut bytes = SketchBytes::with_capacity(256);
 
@@ -526,12 +526,12 @@ impl CpcSketch {
         bytes.into_bytes()
     }
 
-    /// Deserializes a CpcSketch from bytes.
+    /// Deserializes a `CpcSketch` from bytes.
     pub fn deserialize(bytes: &[u8]) -> Result<Self, Error> {
         Self::deserialize_with_seed(bytes, DEFAULT_UPDATE_SEED)
     }
 
-    /// Deserializes a CpcSketch from bytes with the provided seed.
+    /// Deserializes a `CpcSketch` from bytes with the provided seed.
     pub fn deserialize_with_seed(bytes: &[u8], seed: u64) -> Result<Self, Error> {
         let mut cursor = SketchSlice::new(bytes);
         let preamble_ints = cursor
@@ -716,7 +716,7 @@ impl CpcSketch {
 
 // testing methods
 impl CpcSketch {
-    /// Validate this sketch is valid.
+    /// Returns `true` if the sketch's internal state is valid.
     ///
     /// This is primarily for testing and validation purposes.
     pub fn validate(&self) -> bool {

datasketches/src/cpc/union.rs

@@ -69,7 +69,7 @@ use crate::cpc::determine_correct_offset;
 use crate::cpc::pair_table::PairTable;
 use crate::hash::DEFAULT_UPDATE_SEED;
 
-/// The union (merge) operation for the CPC sketches.
+/// Union operator for CPC sketches.
 #[derive(Debug, Clone)]
 pub struct CpcUnion {
     // immutable config variables
@@ -108,15 +108,15 @@ impl CpcUnion {
         Self { lg_k, seed, state }
     }
 
-    /// Return the parameter lg_k.
+    /// Returns the current `lg_k`.
     ///
-    /// Note that due to merging with source sketches that may have a lower value of lg_k, this
+    /// Note that due to merging with source sketches that may have a lower `lg_k`, this
     /// value can be less than what the union object was configured with.
     pub fn lg_k(&self) -> u8 {
         self.lg_k
     }
 
-    /// Get the union result as a new sketch.
+    /// Returns the union result as a new sketch.
     ///
     /// # Examples
     ///
@@ -207,7 +207,7 @@ impl CpcUnion {
         }
     }
 
-    /// Update this union with a CpcSketch.
+    /// Updates this union with a `CpcSketch`.
     ///
     /// # Panics
     ///