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

doxygen: document envelope functions
---

diff --git a/envelope.c b/envelope.c
index 9c3677bbc..01707d328 100644
--- a/envelope.c
+++ b/envelope.c
@@ -20,6 +20,18 @@
  * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @page envelope Representation of an email header (envelope)
+ *
+ * Representation of an email header (envelope)
+ *
+ * | Function                     | Description
+ * | :--------------------------- | :---------------------------------------------------------
+ * | mutt_free_envelope           | Free an Envelope
+ * | mutt_merge_envelopes         | Merge the headers of two Envelopes
+ * | mutt_new_envelope            | Create a new Envelope
+ */
+
 #include "config.h"
 #include <stddef.h>
 #include "lib/buffer.h"
@@ -28,6 +40,10 @@
 #include "envelope.h"
 #include "rfc822.h"
 
+/**
+ * mutt_new_envelope - Create a new Envelope
+ * @retval ptr New Envelope
+ */
 struct Envelope *mutt_new_envelope(void)
 {
   struct Envelope *e = safe_calloc(1, sizeof(struct Envelope));
@@ -37,6 +53,10 @@ struct Envelope *mutt_new_envelope(void)
   return e;
 }
 
+/**
+ * mutt_free_envelope - Free an Envelope
+ * @param p Envelope to free
+ */
 void mutt_free_envelope(struct Envelope **p)
 {
   if (!*p)
@@ -75,15 +95,18 @@ void mutt_free_envelope(struct Envelope **p)
 }
 
 /**
- * mutt_merge_envelopes - Merge the headers of two emails
+ * mutt_merge_envelopes - Merge the headers of two Envelopes
+ * @param base  Envelope destination for all the headers
+ * @param extra Envelope to copy from
  *
- * Move all the headers from extra not present in base into base
+ * Any fields that are missing from base will be copied from extra.
+ * extra will be freed afterwards.
  */
 void mutt_merge_envelopes(struct Envelope *base, struct Envelope **extra)
 {
 /* copies each existing element if necessary, and sets the element
-  * to NULL in the source so that mutt_free_envelope doesn't leave us
-  * with dangling pointers. */
+ * to NULL in the source so that mutt_free_envelope doesn't leave us
+ * with dangling pointers. */
 #define MOVE_ELEM(h)                                                           \
   if (!base->h)                                                                \
   {                                                                            \
diff --git a/mbox.c b/mbox.c
index a48d78838..7324ca192 100644
--- a/mbox.c
+++ b/mbox.c
@@ -595,6 +595,12 @@ static int strict_cmp_stailq(const struct ListHead *ah, const struct ListHead *b
   return 1;
 }
 
+/**
+ * strict_cmp_envelopes - Strictly compare two Envelopes
+ * @param e1 First Envelope
+ * @param e2 Second Envelope
+ * @retval true Envelopes are strictly identical
+ */
 static int strict_cmp_envelopes(const struct Envelope *e1, const struct Envelope *e2)
 {
   if (e1 && e2)