From 2ae8976579e1b0b4933a96ad7a901ee07365db75 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Mon, 6 Jun 2016 14:22:56 +0200 Subject: [PATCH] Improved comments --- xxhash.h | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/xxhash.h b/xxhash.h index bad3745..ea56ada 100644 --- a/xxhash.h +++ b/xxhash.h @@ -197,22 +197,23 @@ XXH_PUBLIC_API XXH_errorcode XXH64_update (XXH64_state_t* statePtr, const void* XXH_PUBLIC_API XXH64_hash_t XXH64_digest (const XXH64_state_t* statePtr); /*! -These functions generate the xxHash of an input provided in multiple segments, -as opposed to provided as a single block. +These functions generate the xxHash of an input of any length provided in multiple segments. +Note that they are slower than single-direct-call functions, due to state management. +For small keys with known size, prefer `XXH32()` and `XXH64()` . -XXH state must first be allocated, using either static or dynamic method provided above. +XXH state must first be allocated, using XXHnn_createState() . Start a new hash by initializing state with a seed, using XXHnn_reset(). Then, feed the hash state by calling XXHnn_update() as many times as necessary. -Obviously, input must be valid, hence allocated and read accessible. +Obviously, input must be allocated and read accessible. The function returns an error code, with 0 meaning OK, and any other value meaning there is an error. Finally, a hash value can be produced anytime, by using XXHnn_digest(). This function returns the nn-bits hash as an int or long long. It's still possible to continue inserting input into the hash state after a digest, -and later on generate some new hashes, by calling again XXHnn_digest(). +and generate some new hashes later on, by calling again XXHnn_digest(). When done, free XXH state space if it was allocated dynamically. */ @@ -239,9 +240,11 @@ XXH_PUBLIC_API XXH64_hash_t XXH64_hashFromCanonical(const XXH64_canonical_t* src #ifdef XXH_STATIC_LINKING_ONLY -/* This part contains definition which shall only be used with static linking. - The prototypes / types defined here are not guaranteed to remain stable. - They could change in a future version, becoming incompatible with a different version of the library */ +/* This section contains definitions which are not guaranteed to remain stable. + They could change in a future version, becoming incompatible with a different version of the library. + They shall only be used with static linking. */ + +/* These definitions allow allocating XXH state statically */ struct XXH32_state_s { unsigned long long total_len; @@ -266,11 +269,11 @@ XXH_PUBLIC_API XXH64_hash_t XXH64_hashFromCanonical(const XXH64_canonical_t* src }; /* typedef'd to XXH64_state_t */ -#ifdef XXH_INCLUDE_BODY -# include "xxhash.c" -#endif +# ifdef XXH_INCLUDE_BODY +# include "xxhash.c" /* include xxhash functions as `static`, for inlining */ +# endif -#endif +#endif /* XXH_STATIC_LINKING_ONLY */ #if defined (__cplusplus)