From: Richard Russon <rich@flatcap.org>
Date: Sun, 12 Nov 2017 02:26:13 +0000 (+0000)
Subject: doxygen: document parameter functions
X-Git-Tag: neomutt-20171208~45
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=57528fdb184e7c12af52f06b1232fda91591435b;p=neomutt

doxygen: document parameter functions
---

diff --git a/mbox.c b/mbox.c
index 7324ca192..44b5ef07e 100644
--- a/mbox.c
+++ b/mbox.c
@@ -625,6 +625,12 @@ static int strict_cmp_envelopes(const struct Envelope *e1, const struct Envelope
   }
 }
 
+/**
+ * strict_cmp_parameters - strictly compare two parameters
+ * @param p1 first parameter
+ * @param p2 second parameter
+ * @retval true parameters are strictly identical
+ */
 static int strict_cmp_parameters(const struct Parameter *p1, const struct Parameter *p2)
 {
   while (p1 && p2)
diff --git a/parameter.c b/parameter.c
index 3f34267e1..a3068e369 100644
--- a/parameter.c
+++ b/parameter.c
@@ -20,9 +20,26 @@
  * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @page parameter Store attributes associated with a MIME part
+ *
+ * Store attributes associated with a MIME part
+ *
+ * | Function                     | Description
+ * | :--------------------------- | :---------------------------------------------------------
+ * | mutt_delete_parameter()      | Delete a matching Parameter
+ * | mutt_free_parameter()        | Free a Parameter
+ * | mutt_get_parameter()         | Find a matching Parameter
+ * | mutt_set_parameter()         | Set a Parameter
+ */
+
 #include "config.h"
 #include "parameter.h"
 
+/**
+ * mutt_free_parameter - Free a Parameter
+ * @param p Parameter to free
+ */
 void mutt_free_parameter(struct Parameter **p)
 {
   struct Parameter *t = *p;
@@ -39,6 +56,13 @@ void mutt_free_parameter(struct Parameter **p)
   *p = 0;
 }
 
+/**
+ * mutt_get_parameter - Find a matching Parameter
+ * @param s String to match
+ * @param p Parameter list
+ * @retval ptr Matching Parameter
+ * @reval NULL No match
+ */
 char *mutt_get_parameter(const char *s, struct Parameter *p)
 {
   for (; p; p = p->next)
@@ -48,6 +72,17 @@ char *mutt_get_parameter(const char *s, struct Parameter *p)
   return NULL;
 }
 
+/**
+ * mutt_set_parameter - Set a Parameter
+ * @param[in]  attribute Attribute to match
+ * @param[in]  value     Value to set
+ * @param[out] p         Parameter that was set
+ *
+ * @note If value is NULL, the Parameter will be deleted
+ *
+ * @note If a matching Parameter isn't found a new one will be allocated.
+ *       The new Parameter will be inserted at the front of the list.
+ */
 void mutt_set_parameter(const char *attribute, const char *value, struct Parameter **p)
 {
   struct Parameter *q = NULL;
@@ -74,6 +109,11 @@ void mutt_set_parameter(const char *attribute, const char *value, struct Paramet
   *p = q;
 }
 
+/**
+ * mutt_delete_parameter - Delete a matching Parameter
+ * @param[in]  attribute Attribute to match
+ * @param[out] p         Parameter after the deleted Parameter
+ */
 void mutt_delete_parameter(const char *attribute, struct Parameter **p)
 {
   for (struct Parameter *q = *p; q; p = &q->next, q = q->next)
diff --git a/parameter.h b/parameter.h
index ceff12f5f..d5d6e45cd 100644
--- a/parameter.h
+++ b/parameter.h
@@ -35,6 +35,10 @@ struct Parameter
   struct Parameter *next;
 };
 
+/**
+ * mutt_new_parameter - Create a new Parameter
+ * @retval ptr Newly allocated Parameter
+ */
 static inline struct Parameter *mutt_new_parameter(void)
 {
   return safe_calloc(1, sizeof(struct Parameter));