Merge branch '252_doxygen_desc_src'

Conflicts:

	src/file.h

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/achown.c

@@ -17,6 +17,10 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  
  */
 
+/** \file achown.c
+ *  \brief Source: Contains functions for advanced chowning
+ */
+
 #include <config.h>
 
 #include <errno.h>

src/achown.h

@@ -1,3 +1,8 @@
+
+/** \file achown.h
+ *  \brief Header: Contains functions for advanced chowning
+ */
+
 #ifndef MC_ACHOWN_H
 #define MC_ACHOWN_H
 

src/background.c

@@ -22,6 +22,10 @@
 
 /* }}} */
 
+/** \file background.c
+ *  \brief Source: Background support
+ */
+
 #include <config.h>
 
 #ifdef WITH_BACKGROUND

src/background.h

@@ -1,3 +1,8 @@
+
+/** \file background.h
+ *  \brief Header: Background support
+ */
+
 #ifndef MC_BACKGROUND_H
 #define MC_BACKGROUND_H
 

src/boxes.c

@@ -20,6 +20,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file boxes.c
+ *  \brief Source: Some misc dialog boxes for the program
+ */
+
 #include <config.h>
 
 #include <ctype.h>

src/boxes.h

@@ -1,3 +1,8 @@
+
+/** \file boxes.h
+ *  \brief Header: Some misc dialog boxes for the program
+ */
+
 #ifndef MC_BOXES_H
 #define MC_BOXES_H
 

src/charsets.c

@@ -17,6 +17,10 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+/** \file charsets.c
+ *  \brief Source: Text conversion from one charset to another
+ */
+
 #include <config.h>
 
 #ifdef HAVE_CHARSET

src/charsets.h

@@ -1,3 +1,8 @@
+
+/** \file charsets.h
+ *  \brief Header: Text conversion from one charset to another
+ */
+
 #ifndef MC_CHARSETS_H
 #define MC_CHARSETS_H
 

src/chmod.c

@@ -17,6 +17,10 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  
  */
 
+/** \file chmod.c
+ *  \brief Source: chmod command
+ */
+
 #include <config.h>
 
 #include <errno.h>

src/chmod.h

@@ -1,3 +1,8 @@
+
+/** \file chmod.h
+ *  \brief Header: chmod command
+ */
+
 #ifndef MC_CHMOD_H
 #define MC_CHMOD_H
 

src/chown.c

@@ -17,6 +17,10 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  
  */
 
+/** \file chown.c
+ *  \brief Source: chown command
+ */
+
 #include <config.h>
 
 #include <errno.h>

src/chown.h

@@ -1,3 +1,8 @@
+
+/** \file chown.h
+ *  \brief Header: chown command
+ */
+
 #ifndef MC_CHOWN_H
 #define MC_CHOWN_H
 

src/cmd.c

@@ -18,6 +18,12 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file cmd.c
+ *  \brief Source: routines invoked by a function key
+ *
+ *  They normally operate on the current panel.
+ */
+
 #include <config.h>
 
 #include <errno.h>

src/cmd.h

@@ -1,3 +1,10 @@
+
+/** \file cmd.h
+ *  \brief Header: routines invoked by a function key
+ *
+ *  They normally operate on the current panel.
+ */
+
 #ifndef MC_CMD_H
 #define MC_CMD_H
 

src/color.c

@@ -16,6 +16,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file color.c
+ *  \brief Source: color setup
+ */
+
 #include <config.h>
 
 #include <stdio.h>

src/color.h

@@ -1,3 +1,8 @@
+
+/** \file color.h
+ *  \brief Header: color setup
+ */
+
 #ifndef MC_COLOR_H
 #define MC_COLOR_H
 

src/command.c

@@ -22,6 +22,10 @@
 
 */
 
+/** \file command.c
+ *  \brief Source: command line widget
+ */
+
 #include <config.h>
 
 #include <errno.h>

src/command.h

@@ -1,3 +1,8 @@
+
+/** \file command.h
+ *  \brief Header: command line widget
+ */
+
 #ifndef MC_COMMAND_H
 #define MC_COMMAND_H
 

src/complete.c

@@ -20,6 +20,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file complete.c
+ *  \brief Source: Input line filename/username/hostname/variable/command completion
+ */
+
 #include <config.h>
 
 #include <ctype.h>

src/cons.handler.c

@@ -16,6 +16,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file cons.handler.c
+ *  \brief Source: client %interface for General purpose Linux console save/restore server
+ */
+
 #include <config.h>
 
 #include <signal.h>

src/cons.saver.c

@@ -32,6 +32,17 @@
    Seeing other peoples consoles is bad thing, but believe me, full
    root is even worse. */
 
+/** \file cons.saver.c
+ *  \brief Source: general purpose Linux console screen save/restore server
+ *
+ *  This code does _not_ need to be setuid root. However, it needs
+ *  read/write access to /dev/vcsa* (which is priviledged
+ *  operation). You should create user vcsa, make cons.saver setuid
+ *  user vcsa, and make all vcsa's owned by user vcsa.
+ *  Seeing other peoples consoles is bad thing, but believe me, full
+ *  root is even worse.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif

src/cons.saver.h

@@ -1,3 +1,15 @@
+
+/** \file cons.saver.h
+ *  \brief Header: general purpose Linux console screen save/restore server
+ *
+ *  This code does _not_ need to be setuid root. However, it needs
+ *  read/write access to /dev/vcsa* (which is priviledged
+ *  operation). You should create user vcsa, make cons.saver setuid
+ *  user vcsa, and make all vcsa's owned by user vcsa.
+ *  Seeing other peoples consoles is bad thing, but believe me, full
+ *  root is even worse.
+ */
+
 #ifndef MC_CONS_SAVER_H
 #define MC_CONS_SAVER_H
 

src/dialog.c

@@ -17,6 +17,10 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+/** \file dialog.c
+ *  \brief Source: dialog box features module
+ */
+
 #include <config.h>
 
 #include <ctype.h>

src/dialog.h

@@ -16,6 +16,10 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+/** \file dialog.h
+ *  \brief Header: dialog box features module
+ */
+
 #ifndef MC_DLG_H
 #define MC_DLG_H
 

src/dir.c

@@ -16,6 +16,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file dir.c
+ *  \brief Source: directory routines
+ */
+
 #include <config.h>
 
 #include <errno.h>

src/dir.h

@@ -1,3 +1,8 @@
+
+/** \file dir.h
+ *  \brief Header: directory routines
+ */
+
 #ifndef MC_DIR_H
 #define MC_DIR_H
 

src/ecs-test.c

@@ -22,6 +22,10 @@
    MA 02110-1301, USA.
  */
 
+/** \file  ecs-test.c
+ *  \brief Source: testsuite for basic support for extended character sets
+ */
+
 #include <config.h>
 
 #undef NDEBUG

src/ecs.c

@@ -22,6 +22,10 @@
    MA 02110-1301, USA.
  */
 
+/** \file  ecs.c
+ *  \brief Source: basic support for extended character sets
+ */
+
 #include <config.h>
 
 #include <assert.h>

src/ecs.h

@@ -22,6 +22,10 @@
    MA 02110-1301, USA.
  */
 
+/** \file  ecs.h
+ *  \brief Header: basic support for extended character sets
+ */
+
 #ifndef MC_ECS_H
 #define MC_ECS_H
 

src/eregex.h

@@ -19,6 +19,10 @@
    Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301 USA.  */
 
+/** \file  eregex.h
+ *  \brief Header: data structures and routines for the regular expression library
+ */
+
 #ifndef USE_INCLUDED_REGEX
 #include <regex.h>
 #else

src/execute.c

@@ -15,6 +15,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file  execute.c
+ *  \brief Source: execution routines
+ */
+
 #include <config.h>
 
 #include <signal.h>

src/execute.h

@@ -1,3 +1,8 @@
+
+/** \file  execute.h
+ *  \brief Header: execution routines
+ */
+
 #ifndef MC_EXECUTE_H
 #define MC_EXECUTE_H
 

src/ext.c

@@ -19,6 +19,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file  ext.c
+ *  \brief Source: extension dependent execution
+ */
+
 #include <config.h>
 
 #include <ctype.h>

src/ext.h

@@ -1,3 +1,8 @@
+
+/** \file  ext.h
+ *  \brief Header: extension dependent execution
+ */
+
 #ifndef MC_EXT_H
 #define MC_EXT_H
 

src/file.c

@@ -37,6 +37,10 @@
  * operations.
  */
 
+/** \file  file.c
+ *  \brief Source: file management
+ */
+
 /* {{{ Include files */
 
 #include <config.h>

src/file.h

@@ -1,4 +1,7 @@
-/* File and directory operation routines for Midnight Commander */
+
+/** \file  file.h
+ *  \brief Header: File and directory operation routines
+ */
 
 #ifndef MC_FILE_H
 #define MC_FILE_H

src/filegui.c

@@ -39,6 +39,9 @@
  * operations.
  */
 
+/** \file  filegui.c
+ *  \brief Source: file management GUI for the text mode edition
+ */
 
 /* {{{ Include files */
 

src/filegui.h

@@ -1,3 +1,8 @@
+
+/** \file  filegui.h
+ *  \brief Header: file management GUI for the text mode edition
+ */
+
 #ifndef MC_FILEGUI_H
 #define MC_FILEGUI_H
 

src/fileloc.h

@@ -1,16 +1,19 @@
+
+/** \file  fileloc.h
+ *  \brief Header: config files list
+ *
+ *  This file defines the locations of the various user specific
+ *  configuration files of the Midnight Commander. Historically the
+ *  system wide and the user specific file names have not always been
+ *  the same, so don't use these names for finding system wide
+ *  configuration files.
+ *
+ *  \todo This inconsistency should disappear in the one of the next versions (5.0?)
+ */
+
 #ifndef MC_FILELOC_H
 #define MC_FILELOC_H
 
-/*
-    This file defines the locations of the various user specific
-    configuration files of the Midnight Commander. Historically the
-    system wide and the user specific file names have not always been
-    the same, so don't use these names for finding system wide
-    configuration files.
-
-    TODO: This inconsistency should disappear in version 5.0.
-*/
-
 #define MC_USERCONF_DIR		".mc"
 
 #define MC_BASHRC_FILE		"bashrc"

src/filenot.c

@@ -22,6 +22,13 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+
+/** \file  filenot.c
+ *  \brief Source: wrapper for routines to notify the
+ *  tree about the changes made to the directory
+ *  structure.
+ */
+
 #include <config.h>
 
 #include <errno.h>

src/fileopctx.c

@@ -21,6 +21,13 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+/** \file fileopctx.c
+ *  \brief Source: file operation contexts
+ *  \date 1998-2007
+ *  \author Federico Mena <federico@nuclecu.unam.mx>
+ *  \author Miguel de Icaza <miguel@nuclecu.unam.mx>
+ */
+
 #include <config.h>
 
 #include <unistd.h>
@@ -30,13 +37,13 @@
 
 
 /**
- * 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)
 {
@@ -59,12 +66,12 @@ 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.
- **/
+ */
 void
 file_op_context_destroy (FileOpContext *ctx)
 {
@@ -75,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/fileopctx.h

@@ -1,9 +1,15 @@
+
+/** \file fileopctx.h
+ *  \brief Header: file operation contexts
+ *  \date 1998
+ *  \author Federico Mena <federico@nuclecu.unam.mx>
+ *  \author Miguel de Icaza <miguel@nuclecu.unam.mx>
+ */
+
 /* File operation contexts for the Midnight Commander
  *
  * Copyright (C) 1998 Free Software Foundation, Inc.
  *
- * Authors: Federico Mena <federico@nuclecu.unam.mx>
- *          Miguel de Icaza <miguel@nuclecu.unam.mx>
  */
 
 #ifndef FILEOPCTX_H

src/find.c

@@ -19,6 +19,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file find.c
+ *  \brief Source: Find file command
+ */
+
 #include <config.h>
 
 #include <ctype.h>

src/find.h

@@ -1,3 +1,8 @@
+
+/** \file find.h
+ *  \brief Header: Find file command
+ */
+
 #ifndef MC_FIND_H
 #define MC_FIND_H
 

src/findme.c

@@ -2,6 +2,10 @@
    file accompanying popt source distributions, available from 
    ftp://ftp.redhat.com/pub/code/popt */
 
+/** \file findme.c
+ *  \brief Source: findProgramPath function
+ */
+
 #include <config.h>
 
 #include "poptalloca.h"

src/findme.h

@@ -2,6 +2,10 @@
    file accompanying popt source distributions, available from
    ftp://ftp.redhat.com/pub/code/popt */
 
+/** \file findme.h
+ *  \brief Header: findProgramPath function
+ */
+
 #ifndef MC_FINDME_H
 #define MC_FINDME_H
 

src/fs.h

@@ -1,3 +1,8 @@
+
+/** \file fs.h
+ *  \brief Header: fs compatibility definitions
+ */
+
 /* Include file to use opendir/closedir/readdir */
 
 #ifndef MC_FS_H

src/fsusage.c

@@ -17,6 +17,12 @@
    along with this program; if not, write to the Free Software Foundation,
    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file fsusage.c
+ *  \brief Source: return space usage of mounted file systems
+ *
+ *  Space usage statistics for a file system.  Blocks are 512-byte
+ */
+
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif

src/fsusage.h

@@ -19,6 +19,13 @@
 
 /* Space usage statistics for a file system.  Blocks are 512-byte. */
 
+/** \file fsusage.h
+ *  \brief Header: return space usage of mounted file systems
+ *
+ *  Space usage statistics for a file system.  Blocks are 512-byte
+ */
+
+
 #if !defined MC_FSUSAGE_H
 # define MC_FSUSAGE_H
 

src/glibcompat.c

@@ -17,7 +17,9 @@
  * Boston, MA 02110-1301, USA.
  */
 
-/*
+/** \file glibcompat.c
+ *  \brief Source: old glib compatibility
+ *
  *  Following code was copied from glib to GNU Midnight Commander to
  *  provide compatibility with older versions of glib.
  */

src/glibcompat.h

@@ -15,6 +15,13 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file glibcompat.h
+ *  \brief Header: old glib compatibility
+ *
+ *  Following code was copied from glib to GNU Midnight Commander to
+ *  provide compatibility with older versions of glib.
+ */
+
 #ifndef MC_GLIBCOMPAT_H
 #define MC_GLIBCOMPAT_H
 

src/global.h

@@ -1,8 +1,11 @@
-/*
- * This file should be included after all system includes and before
- * all local includes.
+
+/** \file global.h
+ *  \brief Header: %global definitions for compatibility
+ *
+ *  This file should be included after all system includes and before all local includes.
  */
 
+
 #ifndef MC_GLOBAL_H
 #define MC_GLOBAL_H
 

src/help.c

@@ -17,29 +17,32 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/*
-   Implements the hypertext file viewer.
-   The hypertext file is a file that may have one or more nodes.  Each
-   node ends with a ^D character and starts with a bracket, then the
-   name of the node and then a closing bracket. Right after the closing
-   bracket a newline is placed. This newline is not to be displayed by
-   the help viewer and must be skipped - its sole purpose is to faciliate
-   the work of the people managing the help file template (xnc.hlp) .
 
-   Links in the hypertext file are specified like this: the text that
-   will be highlighted should have a leading ^A, then it comes the
-   text, then a ^B indicating that highlighting is done, then the name
-   of the node you want to link to and then a ^C.
+/** \file help.c
+ *  \brief Source: hypertext file browser
+ *
+ *  Implements the hypertext file viewer.
+ *  The hypertext file is a file that may have one or more nodes.  Each
+ *  node ends with a ^D character and starts with a bracket, then the
+ *  name of the node and then a closing bracket. Right after the closing
+ *  bracket a newline is placed. This newline is not to be displayed by
+ *  the help viewer and must be skipped - its sole purpose is to faciliate
+ *  the work of the people managing the help file template (xnc.hlp) .
+ *
+ *  Links in the hypertext file are specified like this: the text that
+ *  will be highlighted should have a leading ^A, then it comes the
+ *  text, then a ^B indicating that highlighting is done, then the name
+ *  of the node you want to link to and then a ^C.
+ *
+ *  The file must contain a ^D at the beginning and at the end of the
+ *  file or the program will not be able to detect the end of file.
+ *
+ *  Lazyness/widgeting attack: This file does use the dialog manager
+ *  and uses mainly the dialog to achieve the help work.  there is only
+ *  one specialized widget and it's only used to forward the mouse messages
+ *  to the appropiate routine.
+ */
 
-   The file must contain a ^D at the beginning and at the end of the
-   file or the program will not be able to detect the end of file.
-
-   Lazyness/widgeting attack: This file does use the dialog manager
-   and uses mainly the dialog to achieve the help work.  there is only
-   one specialized widget and it's only used to forward the mouse messages
-   to the appropiate routine.
-   
-*/
 
 #include <config.h>
 

src/help.h

@@ -1,8 +1,34 @@
+
+/** \file help.h
+ *  \brief Header: hypertext file browser
+ *
+ *  Implements the hypertext file viewer.
+ *  The hypertext file is a file that may have one or more nodes.  Each
+ *  node ends with a ^D character and starts with a bracket, then the
+ *  name of the node and then a closing bracket. Right after the closing
+ *  bracket a newline is placed. This newline is not to be displayed by
+ *  the help viewer and must be skipped - its sole purpose is to faciliate
+ *  the work of the people managing the help file template (xnc.hlp) .
+ *
+ *  Links in the hypertext file are specified like this: the text that
+ *  will be highlighted should have a leading ^A, then it comes the
+ *  text, then a ^B indicating that highlighting is done, then the name
+ *  of the node you want to link to and then a ^C.
+ *
+ *  The file must contain a ^D at the beginning and at the end of the
+ *  file or the program will not be able to detect the end of file.
+ *
+ *  Lazyness/widgeting attack: This file does use the dialog manager
+ *  and uses mainly the dialog to achieve the help work.  there is only
+ *  one specialized widget and it's only used to forward the mouse messages
+ *  to the appropiate routine.
+ *
+ *  This file is included by help.c and man2hlp.c
+ */
+
 #ifndef MC_HELP_H
 #define MC_HELP_H
 
-/* This file is included by help.c and man2hlp.c */
-
 #define HELP_TEXT_WIDTH 58
 
 /* Markers used in the help files */

src/history.h

@@ -1,3 +1,8 @@
+
+/** \file history.h
+ *  \brief Header: defines history section names
+ */
+
 #ifndef __MC_HISTORY_H
 #define __MC_HISTORY_H
 

src/hotlist.c

@@ -27,6 +27,10 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  
  */
 
+/** \file hotlist.c
+ *  \brief Source: directory hotlist
+ */
+
 #include <config.h>
 
 #include <ctype.h>

src/hotlist.h

@@ -1,3 +1,8 @@
+
+/** \file hotlist.h
+ *  \brief Header: directory hotlist
+ */
+
 #ifndef MC_HOTLIST_H
 #define MC_HOTLIST_H
 

src/info.c

@@ -16,6 +16,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file info.c
+ *  \brief Source: panel managing
+ */
+
 #include <config.h>
 
 #include <stdio.h>

src/info.h

@@ -1,3 +1,8 @@
+
+/** \file info.h
+ *  \brief Header: panel managing
+ */
+
 #ifndef MC_INFO_H
 #define MC_INFO_H
 

src/key.c

@@ -22,6 +22,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file key.c
+ *  \brief Source: keyboard support routines
+ */
+
 #include <config.h>
 
 #include <ctype.h>

src/key.h

@@ -1,3 +1,8 @@
+
+/** \file key.h
+ *  \brief Header: keyboard support routines
+ */
+
 #ifndef MC_KEY_H
 #define MC_KEY_H
 

src/keyxdef.c

@@ -22,9 +22,10 @@
 
 /* }}} */
 
-/*
- * PURPOSE:
+/** \file keyxdef.c
+ *  \brief Source: additional keyboard support routines
  *
+ * PURPOSE:
  *   We would like to support the direct ALT-?/META-? and some other 'extra'
  *   keyboard functionality provided by some terminals under some OSes (and
  *   not supported by the 'learn keys...' facility of 'mc'.
@@ -37,6 +38,7 @@
  *   try to define a superset of the possible key identifiers here.
  *
  */
+
 #include <config.h>
 
 #include "global.h"

src/layout.c

@@ -20,6 +20,10 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  
  */
 
+/** \file layout.c
+ *  \brief Source: panel layout module
+ */
+
 #include <config.h>
 
 #include <signal.h>

src/layout.h

@@ -1,3 +1,8 @@
+
+/** \file layout.h
+ *  \brief Header: panel layout module
+ */
+
 #ifndef MC_LAYOUT_H
 #define MC_LAYOUT_H
 

src/learn.c

@@ -19,6 +19,10 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  
  */
 
+/** \file learn.c
+ *  \brief Source: learn keys module
+ */
+
 #include <config.h>
 
 #include <ctype.h>

src/learn.h

@@ -1,3 +1,8 @@
+
+/** \file learn.h
+ *  \brief Header: learn keys module
+ */
+
 #ifndef MC_LEARN_H
 #define MC_LEARN_H
 

src/listmode.c

@@ -20,6 +20,10 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  
  */
 
+/** \file listmode.c
+ *  \brief Source: directory panel listing format editor
+ */
+
 #include <config.h>
 
 #ifdef LISTMODE_EDITOR

src/listmode.h

@@ -1,3 +1,8 @@
+
+/** \file listmode.h
+ *  \brief Header: directory panel listing format editor
+ */
+
 #ifndef MC_LISTMODE_H
 #define MC_LISTMODE_H
 

src/logging.c

@@ -21,6 +21,10 @@
    MA 02110-1301, USA.
  */
 
+/** \file logging.c
+ *  \brief Source: provides a log file to ease tracing the program
+ */
+
 #include <config.h>
 
 #include <stdarg.h>

src/logging.h

@@ -1,3 +1,8 @@
+
+/** \file logging.h
+ *  \brief Header: provides a log file to ease tracing the program
+ */
+
 #ifndef MC_LOGGING_H
 #define MC_LOGGING_H
 

src/main-widgets.h

@@ -1,3 +1,8 @@
+
+/** \file main-widgets.h
+ *  \brief Header: provides definitions for some widgets
+ */
+
 #ifndef MC_MAIN_WIDGETS_H
 #define MC_MAIN_WIDGETS_H
 

src/main.c

@@ -20,6 +20,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file main.c
+ *  \brief Source: this is a main module
+ */
+
 #include <config.h>
 
 #include <ctype.h>

src/main.h

@@ -1,3 +1,8 @@
+
+/** \file main.h
+ *  \brief Header: this is a main module header
+ */
+
 #ifndef MC_MAIN_H
 #define MC_MAIN_H
 

src/man2hlp.c

@@ -18,6 +18,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file man2hlp.c
+ *  \brief Source: man page to help file converter
+ */
+
 #include <config.h>
 
 #include <stdarg.h>

src/menu.c

@@ -16,6 +16,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file menu.c
+ *  \brief Source: pulldown menu code
+ */
+
 #include <config.h>
 
 #include <ctype.h>

src/menu.h

@@ -1,3 +1,8 @@
+
+/** \file menu.h
+ *  \brief Header: pulldown menu code
+ */
+
 #ifndef MC_MENU_H
 #define MC_MENU_H
 

src/mfmt.c

@@ -16,6 +16,10 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+/** \file mfmt.c
+ *  \brief Source: sets bold and underline for mail files
+ */
+
 #include <stdio.h>
 
 enum states {

src/mountlist.c

@@ -15,6 +15,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file mountlist.c
+ *  \brief Source: list of mounted filesystems
+ */
+
 #include <config.h>
 
 #include <stdio.h>

src/mountlist.h

@@ -15,6 +15,10 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
+/** \file mountlist.h
+ *  \brief Header: list of mounted filesystems
+ */
+
 #ifndef MC_MOUNTLIST_H
 #define MC_MOUNTLIST_H
 

src/mouse.c

@@ -16,8 +16,11 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
-/* Events received by clients of this library have their coordinates 0 */
-/* based */
+/** \file mouse.c
+ *  \brief Source: mouse managing
+ *
+ *  Events received by clients of this library have their coordinates 0 based
+ */
 
 #include <config.h>
 

src/mouse.h

@@ -1,3 +1,10 @@
+
+/** \file mouse.h
+ *  \brief Header: mouse managing
+ *
+ *  Events received by clients of this library have their coordinates 0 based
+ */
+
 #ifndef MC_MOUSE_H
 #define MC_MOUSE_H