fix header doc comments

include/khash.h

@@ -7,6 +7,12 @@ extern "C" {
 
 #include <stdint.h>
 
+#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