murmur3: Add Doxygen documentation

The interface has been stable for some time now.
This commit is contained in:
Timothy Gu 2016-08-01 23:03:24 -07:00
parent 0a7a4e33f3
commit 39211cb9aa
1 changed files with 64 additions and 0 deletions

View File

@ -34,13 +34,77 @@
* @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]);
/**