From: Richard Russon <rich@flatcap.org>
Date: Sat, 4 Aug 2018 22:19:43 +0000 (+0100)
Subject: doxy: cache
X-Git-Tag: 2019-10-25~712^2~1
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=37cce81fd6874ee926dfff755d3ae25a016a3054;p=neomutt

doxy: cache
---

diff --git a/bcache.h b/bcache.h
index 056615e86..80b5ada7b 100644
--- a/bcache.h
+++ b/bcache.h
@@ -33,7 +33,14 @@ struct BodyCache;
 extern char *MessageCachedir;
 
 /**
- * Callback function for mutt_bcache_list
+ * bcache_list_t - Prototype for mutt_bcache_list() callback
+ * @param bcache  Body Cache from mutt_bcache_open()
+ * @param want_id Callback function called for each match
+ * @param data    Data to pass to the callback function
+ * @retval -1  Failure
+ * @retval >=0 count of matching items
+ *
+ * mutt_bcache_list() will call this function once for each item in the cache.
  */
 typedef int bcache_list_t(const char *id, struct BodyCache *bcache, void *data);
 
diff --git a/config/set.c b/config/set.c
index a4306a0c4..6b4588a5f 100644
--- a/config/set.c
+++ b/config/set.c
@@ -45,7 +45,7 @@ struct ConfigSetType RegisteredTypes[18] = {
 };
 
 /**
- * destroy - Callback function for the Hash Table
+ * destroy - Callback function for the Hash Table - Implements ::hash_destructor_t
  * @param type Object type, e.g. #DT_STRING
  * @param obj  Object to destroy
  * @param data ConfigSet associated with the object
diff --git a/email/thread.c b/email/thread.c
index 1c0fcd9e6..0b7e8480b 100644
--- a/email/thread.c
+++ b/email/thread.c
@@ -101,10 +101,7 @@ void insert_message(struct MuttThread **new, struct MuttThread *newparent,
 }
 
 /**
- * thread_hash_destructor - Hash Destructor callback
- * @param type Hash Type
- * @param obj  Object to free
- * @param data Data associated with the Hash
+ * thread_hash_destructor - Hash Destructor callback - Implements ::hash_destructor_t
  */
 void thread_hash_destructor(int type, void *obj, intptr_t data)
 {
diff --git a/hcache/hcache.c b/hcache/hcache.c
index 1cafa7d3f..27a5e16f5 100644
--- a/hcache/hcache.c
+++ b/hcache/hcache.c
@@ -165,7 +165,7 @@ static bool create_hcache_dir(const char *path)
  * hcache_per_folder - Generate the hcache pathname
  * @param path   Base directory, from $header_cache
  * @param folder Mailbox name (including protocol)
- * @param namer  Callback to generate database filename
+ * @param namer  Callback to generate database filename - Implements ::hcache_namer_t
  * @retval ptr Full pathname to the database (to be generated)
  *             (path must be freed by the caller)
  *
diff --git a/hcache/hcache.h b/hcache/hcache.h
index 8aac251ab..ff583aa8c 100644
--- a/hcache/hcache.h
+++ b/hcache/hcache.h
@@ -71,6 +71,13 @@ struct HeaderCache
 
 typedef struct HeaderCache header_cache_t;
 
+/**
+ * hcache_namer_t - Prototype for function to compose hcache file names
+ * @param path    Path of message
+ * @param dest    Buffer for filename
+ * @param destlen Length of buffer
+ * @retval num Characters written to buffer
+ */
 typedef int (*hcache_namer_t)(const char *path, char *dest, size_t dlen);
 
 /**
diff --git a/imap/message.c b/imap/message.c
index 62d235e83..1021235c7 100644
--- a/imap/message.c
+++ b/imap/message.c
@@ -171,10 +171,7 @@ static int msg_cache_commit(struct ImapData *idata, struct Header *h)
 }
 
 /**
- * msg_cache_clean_cb - Delete an entry from the message cache
- * @param id     ID of entry to delete
- * @param bcache BodyCache
- * @param data   Server data
+ * msg_cache_clean_cb - Delete an entry from the message cache - Implements ::bcache_list_t
  * @retval 0 Always
  */
 static int msg_cache_clean_cb(const char *id, struct BodyCache *bcache, void *data)
diff --git a/imap/util.c b/imap/util.c
index 0b0aa606d..400fd5bab 100644
--- a/imap/util.c
+++ b/imap/util.c
@@ -211,11 +211,7 @@ void imap_clean_path(char *path, size_t plen)
 
 #ifdef USE_HCACHE
 /**
- * imap_hcache_namer - Generate a filename for the header cache
- * @param path Path for the header cache file
- * @param dest Buffer for result
- * @param dlen Length of buffer
- * @retval num Chars written to dest
+ * imap_hcache_namer - Generate a filename for the header cache - Implements ::hcache_namer_t
  */
 static int imap_hcache_namer(const char *path, char *dest, size_t dlen)
 {
diff --git a/mutt/hash.c b/mutt/hash.c
index e493c7e89..ed1b7eca5 100644
--- a/mutt/hash.c
+++ b/mutt/hash.c
@@ -317,7 +317,7 @@ struct Hash *mutt_hash_int_create(size_t nelem, int flags)
  * @param fn      Callback function to free Hash Table's resources
  * @param fn_data Data to pass to the callback function
  */
-void mutt_hash_set_destructor(struct Hash *table, hash_destructor fn, intptr_t fn_data)
+void mutt_hash_set_destructor(struct Hash *table, hash_destructor_t fn, intptr_t fn_data)
 {
   table->destroy = fn;
   table->dest_data = fn_data;
diff --git a/mutt/hash.h b/mutt/hash.h
index 28d8bfd96..c96d642dd 100644
--- a/mutt/hash.h
+++ b/mutt/hash.h
@@ -47,7 +47,13 @@ struct HashElem
   struct HashElem *next;
 };
 
-typedef void (*hash_destructor)(int type, void *obj, intptr_t data);
+/**
+ * hash_destructor_t - Prototype for Hash Destructor callback function
+ * @param type Hash Type
+ * @param obj  Object to free
+ * @param data Data associated with the Hash
+ */
+typedef void (*hash_destructor_t)(int type, void *obj, intptr_t data);
 
 /**
  * struct Hash - A Hash Table
@@ -60,7 +66,7 @@ struct Hash
   struct HashElem **table;
   size_t (*gen_hash)(union HashKey, size_t);
   int (*cmp_key)(union HashKey, union HashKey);
-  hash_destructor destroy;
+  hash_destructor_t destroy;
   intptr_t dest_data;
 };
 
@@ -80,7 +86,7 @@ struct Hash *    mutt_hash_int_create(size_t nelem, int flags);
 void             mutt_hash_int_delete(struct Hash *table, unsigned int intkey, const void *data);
 void *           mutt_hash_int_find(const struct Hash *table, unsigned int intkey);
 struct HashElem *mutt_hash_int_insert(struct Hash *table, unsigned int intkey, void *data);
-void             mutt_hash_set_destructor(struct Hash *table, hash_destructor fn, intptr_t fn_data);
+void             mutt_hash_set_destructor(struct Hash *table, hash_destructor_t fn, intptr_t fn_data);
 struct HashElem *mutt_hash_typed_insert(struct Hash *table, const char *strkey, int type, void *data);
 
 /**
diff --git a/nntp/newsrc.c b/nntp/newsrc.c
index e3997e49a..85e599159 100644
--- a/nntp/newsrc.c
+++ b/nntp/newsrc.c
@@ -133,12 +133,9 @@ void nntp_data_free(void *data)
 }
 
 /**
- * nntp_hash_destructor - Free our hash table data
- * @param type Type (UNUSED)
- * @param obj  NNTP data
- * @param data Data (UNUSED)
+ * nntp_hash_destructor_t - Free our hash table data - Implements ::hash_destructor_t
  */
-void nntp_hash_destructor(int type, void *obj, intptr_t data)
+void nntp_hash_destructor_t(int type, void *obj, intptr_t data)
 {
   nntp_data_free(obj);
 }
@@ -710,13 +707,7 @@ int nntp_active_save_cache(struct NntpServer *nserv)
 
 #ifdef USE_HCACHE
 /**
- * nntp_hcache_namer - Compose hcache file names
- * @param path    Path of message
- * @param dest    Buffer for filename
- * @param destlen Length of buffer
- * @retval num Characters written to buffer
- *
- * Used by mutt_hcache_open() to compose hcache file name
+ * nntp_hcache_namer - Compose hcache file names - Implements ::hcache_namer_t
  */
 static int nntp_hcache_namer(const char *path, char *dest, size_t destlen)
 {
@@ -808,10 +799,7 @@ void nntp_hcache_update(struct NntpData *nntp_data, header_cache_t *hc)
 #endif
 
 /**
- * nntp_bcache_delete - Remove bcache file
- * @param id     Body cache ID
- * @param bcache Body cache
- * @param data   NNTP data
+ * nntp_bcache_delete - Remove bcache file - Implements ::bcache_list_t
  * @retval 0 Always
  */
 static int nntp_bcache_delete(const char *id, struct BodyCache *bcache, void *data)
@@ -1098,7 +1086,7 @@ struct NntpServer *nntp_select_server(char *server, bool leave_lock)
   nserv = mutt_mem_calloc(1, sizeof(struct NntpServer));
   nserv->conn = conn;
   nserv->groups_hash = mutt_hash_create(1009, 0);
-  mutt_hash_set_destructor(nserv->groups_hash, nntp_hash_destructor, 0);
+  mutt_hash_set_destructor(nserv->groups_hash, nntp_hash_destructor_t, 0);
   nserv->groups_max = 16;
   nserv->groups_list = mutt_mem_malloc(nserv->groups_max * sizeof(nntp_data));
 
diff --git a/pop/pop.c b/pop/pop.c
index d2dd1cd1e..ca568d18b 100644
--- a/pop/pop.c
+++ b/pop/pop.c
@@ -242,12 +242,7 @@ static int fetch_uidl(char *line, void *data)
 }
 
 /**
- * msg_cache_check - Check the Body Cache for an ID
- * @param id     Cache ID
- * @param bcache Body cache
- * @param data   Mailbox Context
- * @retval  0 Success
- * @retval -1 Failure
+ * msg_cache_check - Check the Body Cache for an ID - Implements ::bcache_list_t
  */
 static int msg_cache_check(const char *id, struct BodyCache *bcache, void *data)
 {
@@ -279,11 +274,7 @@ static int msg_cache_check(const char *id, struct BodyCache *bcache, void *data)
 
 #ifdef USE_HCACHE
 /**
- * pop_hcache_namer - Create a header cache filename for a POP mailbox
- * @param path    Path of mailbox
- * @param dest    Buffer for filename
- * @param destlen Length of buffer
- * @retval num Characters written to buffer
+ * pop_hcache_namer - Create a header cache filename for a POP mailbox - Implements ::hcache_namer_t
  */
 static int pop_hcache_namer(const char *path, char *dest, size_t destlen)
 {