From f44fdfe9e49c372aad84a8d265a4bcdba7304cb3 Mon Sep 17 00:00:00 2001
From: Richard Russon <rich@flatcap.org>
Date: Wed, 18 Oct 2017 17:36:25 +0100
Subject: [PATCH] doxygen: fix a few warnings

---
 attach.c             |  3 +--
 attach.h             |  3 +++
 doxygen/doxygen.conf | 12 ++++++------
 imap/imap.c          |  6 +++---
 keymap.c             |  9 +++++----
 lib/date.c           |  2 +-
 lib/file.c           |  9 ++++++---
 list.h               |  5 ++++-
 mutt_curses.h        |  2 +-
 mutt_notmuch.c       |  2 +-
 mutt_tags.c          | 30 +++++++++++++++++-------------
 mutt_tags.h          |  3 +--
 ncrypt/crypt_mod.c   |  5 ++---
 13 files changed, 51 insertions(+), 40 deletions(-)

diff --git a/attach.c b/attach.c
index dc2e9bdd3..47065f8e6 100644
--- a/attach.c
+++ b/attach.c
@@ -356,8 +356,7 @@ void mutt_check_lookup_list(struct Body *b, char *type, int len)
  * @param a      The message body containing the attachment
  * @param flag   Option flag for how the attachment should be viewed
  * @param hdr    Message header for the current message. Can be NULL
- * @param idx    Attachment
- * @param idxlen Number of attachments
+ * @param actx   Attachment context
  * @retval 0  If the viewer is run and exited succesfully
  * @retval -1 Error
  * @retval n  Return value of mutt_do_pager() when it is used
diff --git a/attach.h b/attach.h
index e87e09ba2..529056ec7 100644
--- a/attach.h
+++ b/attach.h
@@ -47,6 +47,9 @@ struct AttachPtr
   unsigned int decrypted : 1; /**< not part of message as stored in the hdr->content. */
 };
 
+/**
+ * struct AttachCtx - A set of attachments
+ */
 struct AttachCtx
 {
   struct Header *hdr; /**< used by recvattach for updating */
diff --git a/doxygen/doxygen.conf b/doxygen/doxygen.conf
index 2ebfcc83c..ff78169ff 100644
--- a/doxygen/doxygen.conf
+++ b/doxygen/doxygen.conf
@@ -779,7 +779,7 @@ INPUT_ENCODING         = UTF-8
 # *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08,
 # *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf and *.qsf.
 
-FILE_PATTERNS          = *.c *.h *.wibble
+FILE_PATTERNS          = *.c *.h
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -794,7 +794,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = doc pgpewrap.c pgppubring.c
+EXCLUDE                = autosetup doc pgpewrap.c pgppubring.c
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -1664,7 +1664,7 @@ INCLUDED_BY_GRAPH      = YES
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-CALL_GRAPH             = NO
+CALL_GRAPH             = YES
 
 # If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller
 # dependency graph for every global function or class method.
@@ -1676,7 +1676,7 @@ CALL_GRAPH             = NO
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-CALLER_GRAPH           = NO
+CALLER_GRAPH           = YES
 
 # If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical
 # hierarchy of all classes instead of a textual one.
@@ -1707,7 +1707,7 @@ DIRECTORY_GRAPH        = YES
 # The default value is: png.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_IMAGE_FORMAT       = png
+DOT_IMAGE_FORMAT       = svg
 
 # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
 # enable generation of interactive SVG images that allow zooming and panning.
@@ -1786,7 +1786,7 @@ DOT_GRAPH_MAX_NODES    = 50
 # Minimum value: 0, maximum value: 1000, default value: 0.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-MAX_DOT_GRAPH_DEPTH    = 0
+MAX_DOT_GRAPH_DEPTH    = 1
 
 # Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
 # background. This is disabled by default, because dot on Windows does not seem
diff --git a/imap/imap.c b/imap/imap.c
index c0cd7c9a3..87abaca5b 100644
--- a/imap/imap.c
+++ b/imap/imap.c
@@ -1355,9 +1355,9 @@ static int imap_edit_message_tags(struct Context *ctx, const char *tags, char *b
 
 /**
  * imap_commit_message_tags - Add/Change/Remove flags from headers
- * @param idata: pointer to a struct ImapData
- * @param h: pointer to a header struct
- *
+ * @param ctx  Context
+ * @param h    Header
+ * @param tags List of tags
  * @retval  0 Success
  * @retval -1 Error
  *
diff --git a/keymap.c b/keymap.c
index 60b12d3e6..6eb6fcc77 100644
--- a/keymap.c
+++ b/keymap.c
@@ -463,10 +463,11 @@ static int retry_generic(int menu, keycode_t *keys, int keyslen, int lastkey)
 
 /**
  * km_dokey - Determine what a keypress should do
- * @retval >0       Function to execute
- * @retval #OP_NULL No function bound to key sequence
- * @retval -1       Error occurred while reading input
- * @retval -2       A timeout or sigwinch occurred
+ * @param menu Menu ID, e.g. #MENU_EDITOR
+ * @retval >0      Function to execute
+ * @retval OP_NULL No function bound to key sequence
+ * @retval -1      Error occurred while reading input
+ * @retval -2      A timeout or sigwinch occurred
  */
 int km_dokey(int menu)
 {
diff --git a/lib/date.c b/lib/date.c
index 675619a50..f46e0226f 100644
--- a/lib/date.c
+++ b/lib/date.c
@@ -626,7 +626,7 @@ int imap_make_date(char *buf, size_t buflen, time_t timestamp)
 
 /**
  * imap_parse_date - Parse date of the form: DD-MMM-YYYY HH:MM:SS +ZZzz
- * @param str Date in string form
+ * @param s Date in string form
  * @retval 0      Error
  * @retval time_t Unix time
  */
diff --git a/lib/file.c b/lib/file.c
index 6e978e76c..e479284a1 100644
--- a/lib/file.c
+++ b/lib/file.c
@@ -1115,9 +1115,12 @@ void mutt_unlink_empty(const char *path)
 
 /**
  * mutt_rename_file - Rename a file
- *
- * This function returns 0 on successful move, 1 on old file doesn't exist,
- * 2 on new file already exists, and 3 on other failure.
+ * @param oldfile Old filename
+ * @param newfile New filename
+ * @retval 0 Success
+ * @retval 1 Old file doesn't exist
+ * @retval 2 New file already exists
+ * @retval 3 Some other error
  *
  * note on access(2) use: No dangling symlink problems here due to
  * safe_fopen().
diff --git a/list.h b/list.h
index 0981b0b4d..774f3b0fa 100644
--- a/list.h
+++ b/list.h
@@ -32,12 +32,15 @@
 
 #include "queue.h"
 
-STAILQ_HEAD(ListHead, ListNode);
+/**
+ * struct ListNode - A generic List node
+ */
 struct ListNode
 {
     char *data;
     STAILQ_ENTRY(ListNode) entries;
 };
+STAILQ_HEAD(ListHead, ListNode);
 
 static inline struct ListNode* mutt_list_insert_head(struct ListHead *h,
                                                      char *s)
diff --git a/mutt_curses.h b/mutt_curses.h
index 269524af9..545f037fb 100644
--- a/mutt_curses.h
+++ b/mutt_curses.h
@@ -187,7 +187,6 @@ enum ColorId
 /**
  * struct ColorLine - A regular expression and a color to highlight a line
  */
-STAILQ_HEAD(ColorLineHead, ColorLine);
 struct ColorLine
 {
   regex_t regex;
@@ -200,6 +199,7 @@ struct ColorLine
   int pair;
   STAILQ_ENTRY(ColorLine) entries;
 };
+STAILQ_HEAD(ColorLineHead, ColorLine);
 
 #define MUTT_PROGRESS_SIZE (1 << 0) /**< traffic-based progress */
 #define MUTT_PROGRESS_MSG  (1 << 1) /**< message-based progress */
diff --git a/mutt_notmuch.c b/mutt_notmuch.c
index 3a22a8936..ffde2d098 100644
--- a/mutt_notmuch.c
+++ b/mutt_notmuch.c
@@ -99,7 +99,7 @@ struct UriTag
   struct UriTag *next;
 };
 
-/*
+/**
  * struct NmHdrData - Notmuch data attached to an email
  *
  * This stores all the Notmuch data associated with an email.
diff --git a/mutt_tags.c b/mutt_tags.c
index b0c65ad41..2a61417be 100644
--- a/mutt_tags.c
+++ b/mutt_tags.c
@@ -31,7 +31,7 @@
 
 /**
  * driver_tags_free - Free tags from a header
- * @param[in] head: pointer to the tags head
+ * @param[in] head List of tags
  *
  * Free the whole tags structure
  */
@@ -54,12 +54,16 @@ void driver_tags_free(struct TagHead *head)
 
 /**
  * driver_tags_get_transformed - Get transformed tags
- * @param[in] head: pointer to the tags head
+ * @param head             List of tags
+ * @param show_hidden      Show hidden tags
+ * @param show_transformed Show transformed tags
+ * @param filter           Match tags to this string
+ * @retval ptr String list of tags
  *
  * Return a new allocated string containing tags separated by space
  */
 static char *driver_tags_getter(struct TagHead *head, bool show_hidden,
-                                bool show_tranformed, char *filter)
+                                bool show_transformed, char *filter)
 {
   if (!head)
     return NULL;
@@ -72,7 +76,7 @@ static char *driver_tags_getter(struct TagHead *head, bool show_hidden,
       continue;
     if (show_hidden || !np->hidden)
     {
-      if (show_tranformed && np->transformed)
+      if (show_transformed && np->transformed)
         mutt_str_append_item(&tags, np->transformed, ' ');
       else
         mutt_str_append_item(&tags, np->name, ' ');
@@ -83,7 +87,7 @@ static char *driver_tags_getter(struct TagHead *head, bool show_hidden,
 
 /**
  * driver_tags_get_transformed - Get transformed tags
- * @param[in] head: pointer to the tags head
+ * @param[in] head List of tags
  *
  * Return a new allocated string containing all tags separated by space with
  * transformation
@@ -95,7 +99,7 @@ char *driver_tags_get_transformed(struct TagHead *head)
 
 /**
  * driver_tags_get - Get tags
- * @param[in] head: pointer to the tags head
+ * @param[in] head List of tags
  *
  * Return a new allocated string containing all tags separated by space
  */
@@ -106,7 +110,7 @@ char *driver_tags_get(struct TagHead *head)
 
 /**
  * driver_tags_get_with_hidden - Get tags with hiddens
- * @param[in] head: pointer to the tags head
+ * @param[in] head List of tags
  *
  * Return a new allocated string containing all tags separated by space even
  * the hiddens.
@@ -118,8 +122,8 @@ char *driver_tags_get_with_hidden(struct TagHead *head)
 
 /**
  * driver_tags_get_transformed_for - Get tranformed tag for a tag name from a header
- * @param[in] tag: char* to the tag to get the transformed version
- * @param[in] head: pointer to the tags head
+ * @param[in] name Tag to transform
+ * @param[in] head List of tags
  *
  * @return string tag
  *
@@ -133,8 +137,8 @@ char *driver_tags_get_transformed_for(char *name, struct TagHead *head)
 
 /**
  * driver_tags_add - Add a tag to header
- * @param[in] head: pointer to the tags head
- * @param[in] new_tag: string representing the new tag
+ * @param[in] head List of tags
+ * @param[in] new_tag string representing the new tag
  *
  * Add a tag to the header tags
  */
@@ -164,8 +168,8 @@ static void driver_tags_add(struct TagHead *head, char *new_tag)
 
 /**
  * driver_tags_replace - Replace all tags
- * @param[in] head: pointer to the tags head
- * @param[in] tags: string of all tags separated by space
+ * @param[in] head List of tags
+ * @param[in] tags string of all tags separated by space
  *
  * @retval  0 If no change are made
  * @retval  1 If tags are updated
diff --git a/mutt_tags.h b/mutt_tags.h
index ac19fcbd3..ef840364b 100644
--- a/mutt_tags.h
+++ b/mutt_tags.h
@@ -35,8 +35,6 @@
  *
  * @sa TagNode
  */
-
-STAILQ_HEAD(TagHead, TagNode);
 struct TagNode
 {
     char *name;
@@ -44,6 +42,7 @@ struct TagNode
     bool hidden;
     STAILQ_ENTRY(TagNode) entries;
 };
+STAILQ_HEAD(TagHead, TagNode);
 
 void driver_tags_free(struct TagHead *head);
 char *driver_tags_get(struct TagHead *head);
diff --git a/ncrypt/crypt_mod.c b/ncrypt/crypt_mod.c
index 73a1cc68f..0ad9c2aaa 100644
--- a/ncrypt/crypt_mod.c
+++ b/ncrypt/crypt_mod.c
@@ -30,14 +30,13 @@
  *
  * A type of a variable to keep track of registered crypto modules.
  */
-
-STAILQ_HEAD(CryptModules, CryptModule)
-modules = STAILQ_HEAD_INITIALIZER(modules);
 struct CryptModule
 {
   struct CryptModuleSpecs *specs;
   STAILQ_ENTRY(CryptModule) entries;
 };
+STAILQ_HEAD(CryptModules, CryptModule)
+modules = STAILQ_HEAD_INITIALIZER(modules);
 
 /**
  * crypto_module_register - Register a new crypto module
-- 
2.40.0