From 92d283916d231704ced5154095b8c563ec8adbff Mon Sep 17 00:00:00 2001
From: Yann Collet <cyan@fb.com>
Date: Tue, 7 May 2024 16:33:33 -0700
Subject: [PATCH] update documentation of XXH3_128bits_withSecretandSeed()

to reflect #894
---
 xxhash.h | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/xxhash.h b/xxhash.h
index e60537d0..25bd16b5 100644
--- a/xxhash.h
+++ b/xxhash.h
@@ -1932,9 +1932,9 @@ XXH_PUBLIC_API void XXH3_generateSecret_fromSeed(XXH_NOESCAPE void* secretBuffer
  * @param secretSize The length of @p secret, in bytes.
  * @param seed       The 64-bit seed to alter the hash result predictably.
  *
- * These variants generate hash values using either
- * @p seed for "short" keys (< @ref XXH3_MIDSIZE_MAX = 240 bytes)
- * or @p secret for "large" keys (>= @ref XXH3_MIDSIZE_MAX).
+ * These variants generate hash values using either:
+ * - @p seed for "short" keys (< @ref XXH3_MIDSIZE_MAX = 240 bytes)
+ * - @p secret for "large" keys (>= @ref XXH3_MIDSIZE_MAX).
  *
  * This generally benefits speed, compared to `_withSeed()` or `_withSecret()`.
  * `_withSeed()` has to generate the secret on the fly for "large" keys.
@@ -1961,24 +1961,33 @@ XXH_PUBLIC_API XXH_PUREF XXH64_hash_t
 XXH3_64bits_withSecretandSeed(XXH_NOESCAPE const void* data, size_t len,
                               XXH_NOESCAPE const void* secret, size_t secretSize,
                               XXH64_hash_t seed);
+
 /*!
  * @brief Calculates 128-bit seeded variant of XXH3 hash of @p data.
  *
- * @param input      The block of data to be hashed, at least @p len bytes in size.
+ * @param data       The memory segment to be hashed, at least @p len bytes in size.
  * @param length     The length of @p data, in bytes.
- * @param secret     The secret data.
- * @param secretSize The length of @p secret, in bytes.
+ * @param secret     The secret used to alter hash result predictably.
+ * @param secretSize The length of @p secret, in bytes (must be >= XXH3_SECRET_SIZE_MIN)
  * @param seed64     The 64-bit seed to alter the hash result predictably.
  *
  * @return @ref XXH_OK on success.
  * @return @ref XXH_ERROR on failure.
  *
- * @see XXH3_64bits_withSecretandSeed()
+ * @see XXH3_64bits_withSecretandSeed(): contract is the same.
+ *
+ * Note: there was a bug in an earlier version of this function (<= v0.8.2)
+ * that would make it generate an incorrect hash value
+ * when @p seed == 0 and @p length < XXH3_MIDSIZE_MAX.
+ * As stated in the contract, the correct hash result must be
+ * the same as XXH3_128bits_withSeed() when @p length < XXH3_MIDSIZE_MAX.
+ * Results generated by this older version are not considered comparable.
  */
 XXH_PUBLIC_API XXH_PUREF XXH128_hash_t
 XXH3_128bits_withSecretandSeed(XXH_NOESCAPE const void* input, size_t length,
                                XXH_NOESCAPE const void* secret, size_t secretSize,
                                XXH64_hash_t seed64);
+
 #ifndef XXH_NO_STREAM
 /*!
  * @brief Resets an @ref XXH3_state_t with secret data to begin a new hash.