Simple doxygen description for files in edit directory.

Mostly \file and \brief tag added.
Some fixes for warnings with existing comments.

Signed-off-by: Mikhail S. Pobolovets <styx.mp@gmail.com>

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>

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"

edit/edit-widget.h

@@ -1,3 +1,8 @@
+
+/** \file
+ *  \brief Header: editor widget WEdit
+ */
+
 #ifndef MC_EDIT_WIDGET_H
 #define MC_EDIT_WIDGET_H
 

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>

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
 

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>

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

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>

edit/editkeys.c

@@ -21,6 +21,10 @@
    02110-1301, USA.
 */
 
+/** \file
+ *  \brief Source: editor key translation
+ */
+
 #include <config.h>
 
 #include <assert.h>

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';
 

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
 

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>

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>

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>

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"

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>

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
 

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>

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 */

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);
 }

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)
 {