From 73752743ec2bbea54ffef9acc25c732cd3726f20 Mon Sep 17 00:00:00 2001 From: Avril Date: Tue, 23 Jun 2020 22:44:35 +0100 Subject: [PATCH] fix header doc comments --- include/khash.h | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/include/khash.h b/include/khash.h index fe41946..19852d1 100644 --- a/include/khash.h +++ b/include/khash.h @@ -7,6 +7,12 @@ extern "C" { #include +#ifdef __GNUC__ +#define _deprecated(x) __attribute__((deprecated)) +#else +#define _deprecated(x) +#endif + #define KHASH_ALGO_DEFAULT ((uint8_t)0) #define KHASH_ALGO_CRC32 ((uint8_t)1) #define KHASH_ALGO_CRC64 ((uint8_t)2) @@ -26,7 +32,7 @@ extern "C" { uint8_t salt_type; uint32_t size; uint8_t* body; - } khash_salt; + } khash_salt _deprecated("Use `khash_ctx` instead."); /// A valid context for khash functinos. Instantiated with `khash_new_context`. typedef struct { @@ -50,19 +56,25 @@ extern "C" { /// Create a new salt. `salt_type` is expected to be one of the above defined `KHASH_SALT_TYPE_*` macros. /// Depending on the type, `data` may be `NULL`. - extern int32_t khash_new_salt(uint8_t salt_type, const void* data, size_t size, khash_salt* output); + extern int32_t khash_new_salt(uint8_t salt_type, const void* data, size_t size, khash_salt* output) _deprecated("Use `khash_new_context` instead."); /// Free a salt allocated with `khash_new_salt`. It is okay to call this multiple times. - extern int32_t khash_free_salt(khash_salt* salt); + extern int32_t khash_free_salt(khash_salt* salt) _deprecated("Use `khash_free_context` instead."); /// Clone a salt allocated with `khash_new_salt`. - extern int32_t khash_clone_salt(const khash_salt* src, khash_salt* dst); + extern int32_t khash_clone_salt(const khash_salt* src, khash_salt* dst) _deprecated("Use `khash_close_context` instead."); + /// Create a new context with the specified algorithm (one of the `KHASH_ALGO_*` macro constants), salt type (one of the `KHASH_SALT_TYPE_*` constants), optional salt `data` and salt length `size`, and output pointer `output`. + /// `data` may be `NULL` if the corresponding `salt_type` does not require an input. extern int32_t khash_new_context(uint8_t algo, uint8_t salt_type, const void* data, size_t size, khash_ctx* output); + /// Free a `khash_ctx` allocated with `khash_new_context`. extern int32_t khash_free_context(khash_ctx* ctx); + /// Clone a `khash_ctx` allocated with `khash_new_context`. The clone is a newly allocated instance. extern int32_t khash_clone_context(const khash_ctx* src, khash_ctx* dst); /// Compute the length of hash required for the specified input. + /// This function does not free `context` after it has been called. extern int32_t khash_length(const khash_ctx* context, const void* data, size_t size, size_t* length); /// Compute the hash and store it in `string`. Will write no more than `strlen` bytes into `string`. + /// This function takes ownership of and frees `context` after it has been called. extern int32_t khash_do(khash_ctx* context, const void* data, size_t size, char* string, size_t strlen); #ifdef __cplusplus