doxygen: document envelope functions

diff --git a/envelope.c b/envelope.c
index 9c3677bbcd87e59361817a0d227a61e173aecc34..01707d3289e6679770cd1eec1d619254ab112736 100644 (file)
--- 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 a48d78838e33ed001566cce90f94ed68faabd09d..7324ca1925b66e513b49ba8eb2d3b2029a53c4df 100644 (file)
--- 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)