diff --git a/edit/bookmark.c b/edit/bookmark.c
index 403b93c33..0cfd52093 100644
--- a/edit/bookmark.c
+++ b/edit/bookmark.c
@@ -20,6 +20,12 @@
    02110-1301, USA.
  */
 
+/** \file
+ *  \brief Source: editor book mark handling
+ *  \author Paul Sheer
+ *  \date 1996, 1997
+ */
+
 #include <config.h>
 
 #include <ctype.h>
diff --git a/edit/choosesyntax.c b/edit/choosesyntax.c
index 78a7718c0..4d8cf702e 100644
--- a/edit/choosesyntax.c
+++ b/edit/choosesyntax.c
@@ -16,6 +16,12 @@
    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+/** \file
+ *  \brief Source: user %interface for syntax %selection
+ *  \author Leonard den Ottolander
+ *  \date 2005, 2006
+ */
+
 #include <config.h>
 
 #include "edit.h"
diff --git a/edit/edit-widget.h b/edit/edit-widget.h
index ab55764af..d69a6d37c 100644
--- a/edit/edit-widget.h
+++ b/edit/edit-widget.h
@@ -1,3 +1,8 @@
+
+/** \file
+ *  \brief Header: editor widget WEdit
+ */
+
 #ifndef MC_EDIT_WIDGET_H
 #define MC_EDIT_WIDGET_H
 
diff --git a/edit/edit.c b/edit/edit.c
index 3697bb5c4..79f8266c1 100644
--- a/edit/edit.c
+++ b/edit/edit.c
@@ -21,6 +21,12 @@
    02110-1301, USA.
 */
 
+/** \file
+ *  \brief Source: editor low level data handling and cursor fundamentals
+ *  \author Paul Sheer
+ *  \date 1996, 1997
+ */
+
 #include <config.h>
 #include <stdio.h>
 #include <stdarg.h>
diff --git a/edit/edit.h b/edit/edit.h
index 3e5f5637e..ee313ca74 100644
--- a/edit/edit.h
+++ b/edit/edit.h
@@ -20,6 +20,13 @@
    02110-1301, USA.
 */
 
+/** \file
+ *  \brief Source: editor low level data handling and cursor fundamentals
+ *  edit.h - main include file
+ *  \author Paul Sheer
+ *  \date 1996, 1997
+ */
+
 #ifndef MC_EDIT_H
 #define MC_EDIT_H
 
diff --git a/edit/editcmd.c b/edit/editcmd.c
index 257ab6efe..58da80903 100644
--- a/edit/editcmd.c
+++ b/edit/editcmd.c
@@ -22,6 +22,12 @@
 
 */
 
+/** \file
+ *  \brief Source: editor high level editing commands
+ *  \author Paul Sheer
+ *  \date 1996, 1997
+ */
+
 /* #define PIPE_BLOCKS_SO_READ_BYTE_BY_BYTE */
 
 #include <config.h>
diff --git a/edit/editcmddef.h b/edit/editcmddef.h
index 213537619..66273f3e4 100644
--- a/edit/editcmddef.h
+++ b/edit/editcmddef.h
@@ -1,8 +1,14 @@
+
+/** \file
+ *  \brief Header: editor constants
+ */
+
 #ifndef MC_EDIT_CMD_DEF_H
 #define MC_EDIT_CMD_DEF_H
 
-/*  in the distant future, keyboards will be invented with a
-    separate key for each one of these commands   *sigh*      */
+/** \todo In the distant future, keyboards will be invented with a
+ *  separate key for each one of these commands *sigh*
+ */
 
 /* special commands */
 #define CK_Insert_Char		-1
diff --git a/edit/editdraw.c b/edit/editdraw.c
index 86ea3f9c7..9c7c763d5 100644
--- a/edit/editdraw.c
+++ b/edit/editdraw.c
@@ -21,6 +21,12 @@
    02110-1301, USA.
 */
 
+/** \file
+ *  \brief Source: editor text drawing
+ *  \author Paul Sheer
+ *  \date 1996, 1997
+ */
+
 #include <config.h>
 #include <stdlib.h>
 #include <stdio.h>
diff --git a/edit/editkeys.c b/edit/editkeys.c
index 2cc6add83..2c3ac84fb 100644
--- a/edit/editkeys.c
+++ b/edit/editkeys.c
@@ -21,6 +21,10 @@
    02110-1301, USA.
 */
 
+/** \file
+ *  \brief Source: editor key translation
+ */
+
 #include <config.h>
 
 #include <assert.h>
diff --git a/edit/editlock.c b/edit/editlock.c
index c9434a252..59e9b0d01 100644
--- a/edit/editlock.c
+++ b/edit/editlock.c
@@ -21,6 +21,23 @@
 
 */
 
+/** \file
+ *  \brief Source: editor file locking
+ *  \author Adam Byrtek
+ *  \date 2003
+ *
+ *  Locking scheme used in mcedit is based on a documentation found
+ *  in JED editor sources. Abstract from lock.c file (by John E. Davis):
+ *
+ *  The basic idea here is quite simple.  Whenever a buffer is attached to
+ *  a file, and that buffer is modified, then attempt to lock the
+ *  file. Moreover, before writing to a file for any reason, lock the
+ *  file. The lock is really a protocol respected and not a real lock.
+ *  The protocol is this: If in the directory of the file is a
+ *  symbolic link with name ".#FILE", the FILE is considered to be locked
+ *  by the process specified by the link.
+ */
+
 #include <config.h>
 #include <signal.h>		/* kill() */
 
@@ -51,19 +68,10 @@ struct lock_s {
     pid_t pid;
 };
 
-/* Locking scheme used in mcedit is based on a documentation found
-   in JED editor sources. Abstract from lock.c file (by John E. Davis):
-
-   The basic idea here is quite simple.  Whenever a buffer is attached to
-   a file, and that buffer is modified, then attempt to lock the
-   file. Moreover, before writing to a file for any reason, lock the
-   file. The lock is really a protocol respected and not a real lock.
-   The protocol is this: If in the directory of the file is a
-   symbolic link with name ".#FILE", the FILE is considered to be locked
-   by the process specified by the link.
-*/
-
-/* Build user@host.domain.pid string (need to be freed) */
+/** \fn static char * lock_build_name (void)
+ *  \brief builds user@host.domain.pid string (need to be freed)
+ *  \return a pointer to lock filename
+ */
 static char *
 lock_build_name (void)
 {
@@ -78,7 +86,7 @@ lock_build_name (void)
     if (!user) user = getenv ("LOGNAME");
     if (!user) user = "";
 
-    /* TODO: Use FQDN, no clean interface, so requires lot of code */
+    /** \todo Use FQDN, no clean interface, so requires lot of code */
     if (gethostname (host, BUF_SIZE - 1) == -1)
 	*host = '\0';
 
diff --git a/edit/editlock.h b/edit/editlock.h
index a6443f881..5ddeeefd4 100644
--- a/edit/editlock.h
+++ b/edit/editlock.h
@@ -1,3 +1,11 @@
+
+/** \file
+ *  \brief Header: editor file locking
+ *  \author Adam Byrtek
+ *  \date 2003
+ *  Look at editlock.c for more details
+ */
+
 #ifndef MC_EDIT_LOCK_H
 #define MC_EDIT_LOCK_H
 
diff --git a/edit/editmenu.c b/edit/editmenu.c
index 596b32fa0..ba7b8cad1 100644
--- a/edit/editmenu.c
+++ b/edit/editmenu.c
@@ -21,6 +21,12 @@
    02110-1301, USA.
 */
 
+/** \file
+ *  \brief Source: editor menu definitions and initialisation
+ *  \author Paul Sheer
+ *  \date 1996, 1997
+ */
+
 #include <config.h>
 
 #include <stdio.h>
diff --git a/edit/editoptions.c b/edit/editoptions.c
index 9011ded63..735d5e102 100644
--- a/edit/editoptions.c
+++ b/edit/editoptions.c
@@ -21,6 +21,12 @@
    02110-1301, USA.
 */
 
+/** \file
+ *  \brief Source: editor options dialog box
+ *  \author Paul Sheer
+ *  \date 1996, 1997
+ */
+
 #include <config.h>
 
 #include <stdio.h>
diff --git a/edit/editwidget.c b/edit/editwidget.c
index e23f0978b..61cef95b2 100644
--- a/edit/editwidget.c
+++ b/edit/editwidget.c
@@ -21,6 +21,12 @@
    02110-1301, USA.
  */
 
+/** \file
+ *  \brief Source: editor initialisation and callback handler
+ *  \author Paul Sheer
+ *  \date 1996, 1997
+ */
+
 #include <config.h>
 
 #include <stdio.h>
diff --git a/edit/syntax.c b/edit/syntax.c
index b517b4a0a..009e25a60 100644
--- a/edit/syntax.c
+++ b/edit/syntax.c
@@ -21,6 +21,19 @@
    02110-1301, USA.
 */
 
+/** \file
+ *  \brief Source: editor syntax highlighting
+ *  \author Paul Sheer
+ *  \date 1996, 1997
+ *
+ *  Mispelled words are flushed from the syntax highlighting rules
+ *  when they have been around longer than
+ *  TRANSIENT_WORD_TIME_OUT seconds. At a cursor rate of 30
+ *  chars per second and say 3 chars + a space per word, we can
+ *  accumulate 450 words absolute max with a value of 60. This is
+ *  below this limit of 1024 words in a context.
+ */
+
 #include <config.h>
 #include <stdio.h>
 #include <stdarg.h>
@@ -43,14 +56,6 @@
 /* bytes */
 #define SYNTAX_MARKER_DENSITY 512
 
-/*
-   Mispelled words are flushed from the syntax highlighting rules
-   when they have been around longer than
-   TRANSIENT_WORD_TIME_OUT seconds. At a cursor rate of 30
-   chars per second and say 3 chars + a space per word, we can
-   accumulate 450 words absolute max with a value of 60. This is
-   below this limit of 1024 words in a context.
- */
 #define TRANSIENT_WORD_TIME_OUT 60
 
 #define UNKNOWN_FORMAT "unknown"
diff --git a/edit/usermap.c b/edit/usermap.c
index 1f5a8b7d5..caf8f4a2c 100644
--- a/edit/usermap.c
+++ b/edit/usermap.c
@@ -18,6 +18,12 @@
    02111-1307, USA.
 */
 
+/** \file
+ *  \brief Source: cooledit.bindings file parser
+ *  \author Vitja Makarov
+ *  \date 2005
+ */
+
 #include <config.h>
 
 #include <ctype.h>
diff --git a/edit/usermap.h b/edit/usermap.h
index fecf03b08..6ea286990 100644
--- a/edit/usermap.h
+++ b/edit/usermap.h
@@ -1,3 +1,10 @@
+
+/** \file
+ *  \brief Header: cooledit.bindings file parser
+ *  \author Vitja Makarov
+ *  \date 2005
+ */
+
 #ifndef MC_USERMAP_H
 #define MC_USERMAP_H
 
diff --git a/edit/wordproc.c b/edit/wordproc.c
index fc16136b1..6021349fc 100644
--- a/edit/wordproc.c
+++ b/edit/wordproc.c
@@ -18,6 +18,12 @@
    02110-1301, USA.
  */
 
+/** \file
+ *  \brief Source: word-processor mode for the editor: does dynamic paragraph formatting
+ *  \author Paul Sheer
+ *  \date 1996
+ */
+
 #include <config.h>
 
 #include <stdio.h>
diff --git a/maint/template.c b/maint/template.c
index 721bb1863..7f2ba8ff5 100644
--- a/maint/template.c
+++ b/maint/template.c
@@ -24,6 +24,15 @@
    MA 02110-1301, USA.
  */
 
+/** \file
+ *  \brief This is a template file (here goes brief description).
+ *  \author Author1
+ *  \author Author2
+ *  \date 20xx
+ *
+ *  Detailed description.
+ */
+
 #include <config.h>
 
 #include <System Headers> /* see maint/headers.txt for details */
diff --git a/src/fileopctx.c b/src/fileopctx.c
index 19e6b1fd2..3c1b5adc9 100644
--- a/src/fileopctx.c
+++ b/src/fileopctx.c
@@ -37,12 +37,12 @@
 
 
 /**
- * file_op_context_new:
+ * \fn FileOpContext * file_op_context_new (FileOperation op)
+ * \param op file operation struct
+ * \return The newly-created context, filled with the default file mask values.
  *
  * Creates a new file operation context with the default values.  If you later want
- * to have a user interface for this, call #file_op_context_create_ui().
- *
- * Return value: The newly-created context, filled with the default file mask values.
+ * to have a user interface for this, call file_op_context_create_ui().
  */
 FileOpContext *
 file_op_context_new (FileOperation op)
@@ -66,8 +66,8 @@ file_op_context_new (FileOperation op)
 
 
 /**
- * file_op_context_destroy:
- * @ctx: The file operation context to destroy.
+ * \fn void file_op_context_destroy (FileOpContext *ctx)
+ * \param ctx The file operation context to destroy.
  *
  * Destroys the specified file operation context and its associated UI data, if
  * it exists.
@@ -82,7 +82,7 @@ file_op_context_destroy (FileOpContext *ctx)
 
     regfree (&ctx->rx);
 
-    /* FIXME: do we need to free ctx->dest_mask? */
+    /** \todo FIXME: do we need to free ctx->dest_mask? */
 
     g_free (ctx);
 }
diff --git a/src/treestore.c b/src/treestore.c
index 702010808..e31a0a02b 100644
--- a/src/treestore.c
+++ b/src/treestore.c
@@ -257,13 +257,10 @@ tree_store_load_from(char *name)
 }
 
 /**
- * tree_store_load:
- * @void: 
- * 
- * Loads the tree from the default location.
- * 
- * Return value: TRUE if success, FALSE otherwise.
- **/
+ * \fn int tree_store_load(void)
+ * \brief Loads the tree from the default location
+ * \return 1 if success (true), 0 otherwise (false)
+ */
 int
 tree_store_load(void)
 {
@@ -362,13 +359,10 @@ tree_store_save_to(char *name)
 }
 
 /**
- * tree_store_save:
- * @void: 
- * 
- * Saves the tree to the default file in an atomic fashion.
- * 
- * Return value: 0 if success, errno on error.
- **/
+ * \fn int tree_store_save(void)
+ * \brief Saves the tree to the default file in an atomic fashion
+ * \return 0 if success, errno on error
+ */
 int
 tree_store_save(void)
 {