X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=libavutil%2Fmurmur3.h;h=6a1694c08df29f83569245da7f691da643f4dde1;hb=79248795d4af6ef4782c528e872dfcc9bbd46d68;hp=f29ed973e987fae8b9fe61e7b44f845bcf0309bd;hpb=517dd04f6df3103a6f2bc20b43b956d055ad983f;p=ffmpeg

diff --git a/libavutil/murmur3.h b/libavutil/murmur3.h
index f29ed973e98..6a1694c08df 100644
--- a/libavutil/murmur3.h
+++ b/libavutil/murmur3.h
@@ -18,15 +18,97 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
+/**
+ * @file
+ * @ingroup lavu_murmur3
+ * Public header for MurmurHash3 hash function implementation.
+ */
+
 #ifndef AVUTIL_MURMUR3_H
 #define AVUTIL_MURMUR3_H
 
 #include <stdint.h>
 
+/**
+ * @defgroup lavu_murmur3 Murmur3
+ * @ingroup lavu_hash
+ * MurmurHash3 hash function implementation.
+ *
+ * MurmurHash3 is a non-cryptographic hash function, of which three
+ * incompatible versions were created by its inventor Austin Appleby:
+ *
+ * - 32-bit output
+ * - 128-bit output for 32-bit platforms
+ * - 128-bit output for 64-bit platforms
+ *
+ * FFmpeg only implements the last variant: 128-bit output designed for 64-bit
+ * platforms. Even though the hash function was designed for 64-bit platforms,
+ * the function in reality works on 32-bit systems too, only with reduced
+ * performance.
+ *
+ * @anchor lavu_murmur3_seedinfo
+ * By design, MurmurHash3 requires a seed to operate. In response to this,
+ * libavutil provides two functions for hash initiation, one that requires a
+ * seed (av_murmur3_init_seeded()) and one that uses a fixed arbitrary integer
+ * as the seed, and therefore does not (av_murmur3_init()).
+ *
+ * To make hashes comparable, you should provide the same seed for all calls to
+ * this hash function -- if you are supplying one yourself, that is.
+ *
+ * @{
+ */
+
+/**
+ * Allocate an AVMurMur3 hash context.
+ *
+ * @return Uninitialized hash context or `NULL` in case of error
+ */
 struct AVMurMur3 *av_murmur3_alloc(void);
+
+/**
+ * Initialize or reinitialize an AVMurMur3 hash context with a seed.
+ *
+ * @param[out] c    Hash context
+ * @param[in]  seed Random seed
+ *
+ * @see av_murmur3_init()
+ * @see @ref lavu_murmur3_seedinfo "Detailed description" on a discussion of
+ * seeds for MurmurHash3.
+ */
 void av_murmur3_init_seeded(struct AVMurMur3 *c, uint64_t seed);
+
+/**
+ * Initialize or reinitialize an AVMurMur3 hash context.
+ *
+ * Equivalent to av_murmur3_init_seeded() with a built-in seed.
+ *
+ * @param[out] c    Hash context
+ *
+ * @see av_murmur3_init_seeded()
+ * @see @ref lavu_murmur3_seedinfo "Detailed description" on a discussion of
+ * seeds for MurmurHash3.
+ */
 void av_murmur3_init(struct AVMurMur3 *c);
+
+/**
+ * Update hash context with new data.
+ *
+ * @param[out] c    Hash context
+ * @param[in]  src  Input data to update hash with
+ * @param[in]  len  Number of bytes to read from `src`
+ */
 void av_murmur3_update(struct AVMurMur3 *c, const uint8_t *src, int len);
+
+/**
+ * Finish hashing and output digest value.
+ *
+ * @param[in,out] c    Hash context
+ * @param[out]    dst  Buffer where output digest value is stored
+ */
 void av_murmur3_final(struct AVMurMur3 *c, uint8_t dst[16]);
 
+/**
+ * @}
+ */
+
 #endif /* AVUTIL_MURMUR3_H */