doxygen: document parameter functions

diff --git a/mbox.c b/mbox.c
index 7324ca1925b66e513b49ba8eb2d3b2029a53c4df..44b5ef07e334c19839cf191d6eed647ecaa601fe 100644 (file)
--- 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 3f34267e1aebb07144a9250311e24635454658d9..a3068e3692c16108ae4ef4534e80ba2358b6d9d8 100644 (file)
--- 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 ceff12f5f2b8debd382cd2adb98838b676bdc26b..d5d6e45cd49720b9df3041d5b9b2b77b6b2355f1 100644 (file)
--- 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));