From aafbce6109b176fa922274cd57bb81915295deb9 Mon Sep 17 00:00:00 2001
From: Rebekah Davis <bekadavis9@gmail.com>
Date: Tue, 12 Mar 2024 15:35:35 -0400
Subject: [PATCH] Add some documentation

---
 tiledb/common/random/random_label.cc | 11 +++++++++++
 tiledb/common/random/random_label.h  | 16 +++++++++++++---
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/tiledb/common/random/random_label.cc b/tiledb/common/random/random_label.cc
index 57654e9d8deb..dafd5a22f3da 100644
--- a/tiledb/common/random/random_label.cc
+++ b/tiledb/common/random/random_label.cc
@@ -49,6 +49,17 @@ std::string RandomLabelGenerator::generate_random_label() {
   return generator.generate();
 }
 
+/**
+ * Wrapper function for `generate_random_label`, which returns a PRNG-generated
+ * label as a 32-digit hexadecimal random number.
+ * (Ex. f258d22d4db9139204eef2b4b5d860cc).
+ *
+ * @pre If multiple labels are generated within the same millisecond, they will
+ * be sorted using a counter on the most significant 4 bytes.
+ * @note Labels may be 0-padded to ensure exactly a 128-bit, 32-digit length.
+ *
+ * @return A random label.
+ */
 std::string random_label() {
   return RandomLabelGenerator::generate_random_label();
 }
diff --git a/tiledb/common/random/random_label.h b/tiledb/common/random/random_label.h
index b48e9d452810..731f36d277d5 100644
--- a/tiledb/common/random/random_label.h
+++ b/tiledb/common/random/random_label.h
@@ -51,6 +51,14 @@ class RandomLabelException : public StatusException {
   }
 };
 
+/**
+ * Generates a pseudeo-random label, formatted as a 32-digit hexadecimal number.
+ * (Ex. f258d22d4db9139204eef2b4b5d860cc).
+ *
+ * @pre If multiple labels are generated within the same millisecond, they will
+ * be sorted using a counter on the most significant 4 bytes.
+ * @note Use of wrapper `random_label()` is encouraged in production code.
+ */
 class RandomLabelGenerator {
  public:
   /* ********************************* */
@@ -118,11 +126,13 @@ class RandomLabelGenerator {
 };
 
 /**
- * Returns a PRNG-generated label as a 32-digit hexadecimal random number.
+ * Wrapper function for `generate_random_label`, which returns a PRNG-generated
+ * label as a 32-digit hexadecimal random number.
  * (Ex. f258d22d4db9139204eef2b4b5d860cc).
  *
- * Note: the random number is actually the combination of two 16-digit numbers.
- * The values are 0-padded to ensure exactly a 128-bit, 32-digit length.
+ * @pre If multiple labels are generated within the same millisecond, they will
+ * be sorted using a counter on the most significant 4 bytes.
+ * @note Labels may be 0-padded to ensure exactly a 128-bit, 32-digit length.
  *
  * @return A random label.
  */