Doxygen documentation for text.h, SFont.h, setup.h, realpath.h, readline.h, palette.h, keyboard.h, io.h, input.h, hotkeys.h, helpfile.h, errors.h; and a basic description for all other headers.

Removed 2 unused function prototypes (They escaped translation)
In each C file, added a #include of its own header, to help doxygen generate a more complete documentation for the C files (and also double-check function prototypes)

All these changes don't change the generated executable, it's still beta 99.0.

git-svn-id: svn://pulkomandy.tk/GrafX2/trunk@752 416bcca6-2ee7-4201-b75f-2eb2f807beb1

SFont.h

@@ -33,6 +33,13 @@
 *  contact me, if you problem isn' addressed anywhere.                  *
 *                                                                       *
 ************************************************************************/
+//////////////////////////////////////////////////////////////////////////////
+///@file SFont.h
+/// Text rendering system, that uses bitmaps as fonts.
+/// Not specific to Grafx2, it writes to SDL_Surface.
+//////////////////////////////////////////////////////////////////////////////
+
+
 #ifndef _SFONT_H_
 #define _SFONT_H_
 
@@ -42,37 +49,44 @@
 extern "C" {
 #endif
 
-// Delcare one variable of this type for each font you are using.
+///
-// To load the fonts, load the font image into YourFont->Surface
+/// Declare one variable of this type for each font you are using.
-// and call InitFont( YourFont );
+/// To load the fonts, load the font image into YourFont->Surface
+/// and call InitFont( YourFont );
 typedef struct {
         SDL_Surface *Surface;   
         int CharPos[512];
         int MaxPos;
 } SFont_Font;
 
-// Initializes the font
+///
-// Font: this contains the suface with the font.
+/// Initializes the font.
-//       The Surface must be loaded before calling this function
+/// @param Font this contains the suface with the font.
+///        The Surface must be loaded before calling this function
 SFont_Font* SFont_InitFont (SDL_Surface *Font);
 
-// Frees the font
+///
-// Font: The font to free
+/// Frees the font.
-//       The font must be loaded before using this function.
+/// @param Font The font to free
+///        The font must be loaded before using this function.
 void SFont_FreeFont(SFont_Font* Font);
 
-// Blits a string to a surface
+///
-// Destination: the suface you want to blit to
+/// Blits a string to a surface.
-// text: a string containing the text you want to blit.
+/// @param Surface The surface you want to blit to.
+/// @param Font    The font to use.
+/// @param text    A string containing the text you want to blit.
+/// @param x       Coordinates to start drawing.
+/// @param y       Coordinates to start drawing.
 void SFont_Write(SDL_Surface *Surface, const SFont_Font *Font, int x, int y,
                                  const char *text);
 
-// Returns the width of "text" in pixels
+/// Returns the width of "text" in pixels
 int SFont_TextWidth(const SFont_Font* Font, const char *text);
-// Returns the height of "text" in pixels (which is always equal to Font->Surface->h)
+/// Returns the height of "text" in pixels (which is always equal to Font->Surface->h)
 int SFont_TextHeight(const SFont_Font* Font);
 
-// Blits a string to Surface with centered x position
+/// Blits a string to Surface with centered x position
 void SFont_WriteCenter(SDL_Surface *Surface, const SFont_Font* Font, int y,
                                            const char *text);
 

brush.c

@@ -34,6 +34,7 @@
 #include "errors.h"
 #include "windows.h"
 #include "sdlscreen.h"
+#include "brush.h"
 
 // Calcul de redimensionnement du pinceau pour éviter les débordements de
 // l'écran et de l'image

brush.h

@@ -19,6 +19,11 @@
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 
+//////////////////////////////////////////////////////////////////////////////
+///@file brush.h
+/// Actions on the brush.
+//////////////////////////////////////////////////////////////////////////////
+
 #ifndef __BRUSH_H_
 #define __BRUSH_H_
 

buttons.h

@@ -19,6 +19,11 @@
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 
+//////////////////////////////////////////////////////////////////////////////
+///@file buttons.h
+/// Almost all the editor actions that are called by the menu are here.
+//////////////////////////////////////////////////////////////////////////////
+
 #ifndef __BOUTONS_H_
 #define __BOUTONS_H_
 

const.h

@@ -24,6 +24,7 @@
 ///@file const.h
 /// Constants (preprocessor defines) and enumerations used anywhere.
 //////////////////////////////////////////////////////////////////////////////
+
 #ifndef _CONST_H_
 #define _CONST_H_
 

engine.h

@@ -19,6 +19,11 @@
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 
+//////////////////////////////////////////////////////////////////////////////
+///@file engine.h
+/// Utility functions for the menu and all windows.
+//////////////////////////////////////////////////////////////////////////////
+
 void Main_handler            (void);
 void Draw_menu_button_frame(byte btn_number,byte pressed);
 void Unselect_bouton          (int btn_number);

errors.h

@@ -17,16 +17,30 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
-// Affiche nom fichier, n° ligne, nom fonction, une chaine et un entier.
+
+//////////////////////////////////////////////////////////////////////////////
+///@file errors.h
+/// Functions and macros for tracing and error reporting.
+//////////////////////////////////////////////////////////////////////////////
+
+/// Prints the source filename, line number, function name, a string and an integer.
 #define DEBUG(y,z) printf("%s %d %s | %s : %d###\n",__FILE__,__LINE__,__func__,y,(unsigned int)z)
 
-// DEBUG en hexadécimal
+/// Same as ::DEBUG but in hexadecimal
 #define DEBUGX(y,z) printf("%s %d %s | %s : %X###\n",__FILE__,__LINE__,__func__,y,(unsigned int)z)
 
+/// Macro to report unimplemented functions.
 #define UNIMPLEMENTED printf("%s %d %s non implémenté !\n",__FILE__,__LINE__,__func__);
 
+/// Macro to report untested functions.
 #define UNTESTED printf("%s %d %s à tester !\n",__FILE__,__LINE__,__func__);
 
+/// Helper function used by the macro ::Error
 void Error_function(int error_code, const char *filename, int line_number, const char *function_name);
-#define Error(n) Error_function(n, __FILE__,__LINE__,__func__)
 
+///
+/// Report a run-time error: It will print to standard output some information
+/// about the calling function, and then:
+/// - If the error code is 0, just do a red screen flash and resume.
+/// - If the error code is non-zero, abort the program.
+#define Error(n) Error_function(n, __FILE__,__LINE__,__func__)

filesel.c

@@ -56,6 +56,7 @@
 #include "readline.h"
 #include "input.h"
 #include "help.h"
+#include "filesel.h"
 
 #define NORMAL_FILE_COLOR    MC_Light // color du texte pour une ligne de fichier non sélectionné
 #define NORMAL_DIRECTORY_COLOR MC_Dark // color du texte pour une ligne de répertoire non sélectionné

filesel.h

@@ -19,4 +19,9 @@
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 
+//////////////////////////////////////////////////////////////////////////////
+///@file filesel.h
+/// Fileselector window, used for loading and saving images and brushes.
+//////////////////////////////////////////////////////////////////////////////
+
 byte Button_Load_or_Save(byte load, byte image);

graph.h

@@ -19,6 +19,11 @@
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 
+//////////////////////////////////////////////////////////////////////////////
+///@file graph.h
+/// Graphic functions that target the screen and/or image.
+//////////////////////////////////////////////////////////////////////////////
+
 void Shade_list_to_lookup_tables(word * list, short step, byte mode, byte * table_inc,
         byte * table_dec
 );

help.h

@@ -19,8 +19,13 @@
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 
-#ifndef __AIDE_H_
+//////////////////////////////////////////////////////////////////////////////
-#define __AIDE_H_
+///@file help.h
+/// Functions related to the help browser. The help data is in helpfile.h
+//////////////////////////////////////////////////////////////////////////////
+
+#ifndef __HELP_H_
+#define __HELP_H_
 
 /*!
     Called to open the help window with the keyboard shortcut.

helpfile.h

@@ -19,26 +19,38 @@
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 
-#include "const.h" // Utilise les enumerations BOUTON_ et SPECIAL_
+//////////////////////////////////////////////////////////////////////////////
+///@file helpfile.h
+/// This is all the text that appears in contextual help and credits.
+///
+/// Note: The source code is kept on a public website, so keep this in mind
+/// if you're thinking of putting an e-mail address in there. At least, use
+/// "\100" instead of @, to help against the most basic email address harversters.
+//////////////////////////////////////////////////////////////////////////////
+
+#include "const.h" // Uses enumerations BUTTON_NUMBERS and SPECIAL_ACTIONS
+
+// Some magic formulas:
 
-// Quelques formules magiques:
 #define HELP_TEXT(x) {'N', x, 0},
-// Génère une ligne 'N' (Normale)
+// Generates a 'N' line (Normal)
 
 #define HELP_LINK(x,y) {'K', x, y},
-// Génère une ligne 'K' (Key)
+// Generates a 'K' line (Key)
 
 #define HELP_BOLD(x) {'S', x, 0},
-// Génère une ligne 'S' (BOLD)
+// Generates a 'S' line (BOLD)
 
 #define HELP_TITLE(x) {'T', x, 0}, {'-', x, 0},
-// Génère une ligne 'T' (Titre partie haute)
+// Generates a 'T' line (Title, upper half)
-// et une deuxième  '-' (Titre partie basse)
+// and a second '-' line (Title, lower half),  with the same text.
-// (pour gérer les gros titres qui occupent deux lignes)
 
 static const T_Help_table helptable_about[] =
 /*
+  Do not exceed 44 characters for normal lines:
   HELP_TEXT ("--------------------------------------------")
+  Do not exceed 22 characters for title lines:
+  HELP_TITLE("======================")
 */
 {
   HELP_TEXT ("") // Laisse de la place pour le logo
@@ -2215,43 +2227,43 @@ T_Help_section Help_section[] =
   HELP_TABLE_DECLARATION(helptable_help)
   HELP_TABLE_DECLARATION(helptable_credits)
 
-  // Attention, dans l'ordre de BUTTON_NUMBERS
+  // Attention, keep the same order as BUTTON_NUMBERS:
-  HELP_TABLE_DECLARATION(helptable_paintbrush     )
+  HELP_TABLE_DECLARATION(helptable_paintbrush)
-  HELP_TABLE_DECLARATION(helptable_adjust      )
+  HELP_TABLE_DECLARATION(helptable_adjust)
-  HELP_TABLE_DECLARATION(helptable_draw       )
+  HELP_TABLE_DECLARATION(helptable_draw)
-  HELP_TABLE_DECLARATION(helptable_curves      )
+  HELP_TABLE_DECLARATION(helptable_curves)
-  HELP_TABLE_DECLARATION(helptable_lines       )
+  HELP_TABLE_DECLARATION(helptable_lines)
-  HELP_TABLE_DECLARATION(helptable_airbrush        )
+  HELP_TABLE_DECLARATION(helptable_airbrush)
-  HELP_TABLE_DECLARATION(helptable_floodfill    )
+  HELP_TABLE_DECLARATION(helptable_floodfill)
-  HELP_TABLE_DECLARATION(helptable_polygons    )
+  HELP_TABLE_DECLARATION(helptable_polygons)
-  HELP_TABLE_DECLARATION(helptable_polyfill     )
+  HELP_TABLE_DECLARATION(helptable_polyfill)
-  HELP_TABLE_DECLARATION(helptable_rectangles   )
+  HELP_TABLE_DECLARATION(helptable_rectangles)
-  HELP_TABLE_DECLARATION(helptable_filled_rectangles     )
+  HELP_TABLE_DECLARATION(helptable_filled_rectangles)
-  HELP_TABLE_DECLARATION(helptable_circles      )
+  HELP_TABLE_DECLARATION(helptable_circles)
-  HELP_TABLE_DECLARATION(helptable_filled_circles     )
+  HELP_TABLE_DECLARATION(helptable_filled_circles)
-  HELP_TABLE_DECLARATION(helptable_grad_rect     )
+  HELP_TABLE_DECLARATION(helptable_grad_rect)
-  HELP_TABLE_DECLARATION(helptable_grad_menu     )
+  HELP_TABLE_DECLARATION(helptable_grad_menu)
-  HELP_TABLE_DECLARATION(helptable_spheres      )
+  HELP_TABLE_DECLARATION(helptable_spheres)
-  HELP_TABLE_DECLARATION(helptable_brush       )
+  HELP_TABLE_DECLARATION(helptable_brush)
-  HELP_TABLE_DECLARATION(helptable_polybrush   )
+  HELP_TABLE_DECLARATION(helptable_polybrush)
-  HELP_TABLE_DECLARATION(helptable_brush_fx )
+  HELP_TABLE_DECLARATION(helptable_brush_fx)
-  HELP_TABLE_DECLARATION(helptable_effects       )
+  HELP_TABLE_DECLARATION(helptable_effects)
-  HELP_TABLE_DECLARATION(helptable_text        )
+  HELP_TABLE_DECLARATION(helptable_text)
-  HELP_TABLE_DECLARATION(helptable_magnifier        )
+  HELP_TABLE_DECLARATION(helptable_magnifier)
-  HELP_TABLE_DECLARATION(helptable_colorpicker      )
+  HELP_TABLE_DECLARATION(helptable_colorpicker)
-  HELP_TABLE_DECLARATION(helptable_resolution        )
+  HELP_TABLE_DECLARATION(helptable_resolution)
-  HELP_TABLE_DECLARATION(helptable_page         )
+  HELP_TABLE_DECLARATION(helptable_page)
-  HELP_TABLE_DECLARATION(helptable_save       )
+  HELP_TABLE_DECLARATION(helptable_save)
-  HELP_TABLE_DECLARATION(helptable_load      )
+  HELP_TABLE_DECLARATION(helptable_load)
-  HELP_TABLE_DECLARATION(helptable_settings   )
+  HELP_TABLE_DECLARATION(helptable_settings)
-  HELP_TABLE_DECLARATION(helptable_clear        )
+  HELP_TABLE_DECLARATION(helptable_clear)
-  HELP_TABLE_DECLARATION(helptable_general         )
+  HELP_TABLE_DECLARATION(helptable_general)
-  HELP_TABLE_DECLARATION(helptable_undo         )
+  HELP_TABLE_DECLARATION(helptable_undo)
-  HELP_TABLE_DECLARATION(helptable_kill         )
+  HELP_TABLE_DECLARATION(helptable_kill)
-  HELP_TABLE_DECLARATION(helptable_quit         )
+  HELP_TABLE_DECLARATION(helptable_quit)
-  HELP_TABLE_DECLARATION(helptable_palette      )
+  HELP_TABLE_DECLARATION(helptable_palette)
-  HELP_TABLE_DECLARATION(helptable_pal_scroll    )
+  HELP_TABLE_DECLARATION(helptable_pal_scroll)
-  HELP_TABLE_DECLARATION(helptable_pal_scroll    )
+  HELP_TABLE_DECLARATION(helptable_pal_scroll)
-  HELP_TABLE_DECLARATION(helptable_color_select     )
+  HELP_TABLE_DECLARATION(helptable_color_select)
-  HELP_TABLE_DECLARATION(helptable_hide       )
+  HELP_TABLE_DECLARATION(helptable_hide)
 };

hotkeys.h

@@ -19,6 +19,13 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file hotkeys.h
+/// Definition of the tables used by the keyboard shortcuts.
+/// The actual data is in hotkeys.c
+//////////////////////////////////////////////////////////////////////////////
+
 #include <stdbool.h>
 #include <SDL.h>
 
@@ -26,15 +33,22 @@
 
 typedef struct
 {
-    word Number;
+    word Number;      ///< Identifier for shortcut. This is a number starting from 0, which matches ::T_Config_shortcut_info.Number
-    char Label[36];
+    char Label[36];   ///< Text to show in the screen where you can edit the shortcut.
-    char Explic1[37];
+    char Explic1[37]; ///< Explanation text (1/3) to show in the screen where you can edit the shortcut.
-    char Explic2[37];
+    char Explic2[37]; ///< Explanation text (2/3) to show in the screen where you can edit the shortcut.
-    char Explic3[37];
+    char Explic3[37]; ///< Explanation text (3/3) to show in the screen where you can edit the shortcut.
-    bool Suppr;       // Shortcut facultatif
+    bool Suppr;       ///< Boolean, true if the shortcut can be removed.
-    word Key;
+    word Key;         ///< Primary shortcut. Value is a keycode, see keyboard.h
-    word Key2;
+    word Key2;        ///< Secondary shortcut. Value is a keycode, see keyboard.h
 } T_Key_config;
 
+/// Table with all the configurable shortcuts, whether they are for a menu button or a special action.
 extern T_Key_config ConfigKey[NB_SHORTCUTS];
+///
+/// Translation table from a shortcut index to a shortcut identifier.
+/// The value is either:
+/// - 0x000 + special shortcut number
+/// - 0x100 + button number (left click)
+/// - 0x200 + button number (right click)
 extern word Ordering[NB_SHORTCUTS];

init.c

@@ -65,6 +65,7 @@
 #include "sdlscreen.h"
 #include "mountlist.h" // read_file_system_list
 #include "loadsave.h" // Image_emergency_backup
+#include "init.h"
 
 // Rechercher la liste et le type des lecteurs de la machine
 

init.h

@@ -18,6 +18,12 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file init.h
+/// Initialization (and some de-initialization) functions.
+//////////////////////////////////////////////////////////////////////////////
+
 void Load_graphics(const char * skin_file);
 void Init_buttons(void);
 void Init_operations(void);

input.h

@@ -19,5 +19,21 @@
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 
+//////////////////////////////////////////////////////////////////////////////
+///@file input.h
+/// Functions for mouse, keyboard and joystick input.
+/// Joystick input is used to emulate mouse on platforms that don't have a
+/// pointing device, ie: the GP2X.
+//////////////////////////////////////////////////////////////////////////////
+
+///
+/// This is the keyboard/mouse/joystick input polling function.
+/// Returns 1 if a significant changed occurred, such as a mouse button pressed
+/// or depressed, or a new keypress was in the keyboard buffer.
+/// The latest input variables are held in ::Key, ::Key_ANSI, ::Mouse_X, ::Mouse_Y, ::Mouse_K.
+/// Note that ::Key and ::Key_ANSI are not persistent, they will be reset to 0
+/// on subsequent calls to ::Get_input().
 int  Get_input(void);
+
+/// Returns true if the keycode has been set as a keyboard shortcut for the function.
 int Is_shortcut(word Key, word function);

io.h

@@ -18,29 +18,60 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+//////////////////////////////////////////////////////////////////////////////
+///@file io.h
+/// Low-level endian-neutral file operations, and also some filesystem operations.
+/// Many of these may seem trivial, but the wrappers eliminate the need for a
+/// forest of preprocessor defines in each file.
+/// You MUST use the functions in this file instead of:
+/// - fread() and fwrite()
+/// - stat()
+/// - fstat()
+/// - opendir()
+/// - readdir()
+/// - Also, don't assume "/" or "\\", use PATH_SEPARATOR
+/// If you don't, you break another platform.
+//////////////////////////////////////////////////////////////////////////////
 
+/// Returns x, swapped if the current target is low-endian. Deprecated, please don't use it.
 word  Endian_magic16(word x);
+/// Returns x, swapped if the current target is low-endian. Deprecated, please don't use it.
 dword Endian_magic32(dword x);
 
+/// Reads a single byte from an open file. Returns true if OK, false if a file i/o error occurred.
 int Read_byte(FILE *file, byte *dest);
+/// Writes a single byte to an open file. Returns true if OK, false if a file i/o error occurred.
 int Write_byte(FILE *file, byte b);
 
+/// Reads several bytes from an open file. Returns true if OK, false if a file i/o error occurred.
 int Read_bytes(FILE *file, void *dest, size_t size);
+/// Writes several bytes to an open file. Returns true if OK, false if a file i/o error occurred.
 int Write_bytes(FILE *file, void *dest, size_t size);
 
+/// Reads a 16-bit Low-Endian word from an open file. Returns true if OK, false if a file i/o error occurred.
 int Read_word_le(FILE *file, word *dest);
+/// Writes a 16-bit Low-Endian word to an open file. Returns true if OK, false if a file i/o error occurred.
 int Write_word_le(FILE *file, word w);
+/// Reads a 32-bit Low-Endian dword from an open file. Returns true if OK, false if a file i/o error occurred.
 int Read_dword_le(FILE *file, dword *dest);
+/// Writes a 32-bit Low-Endian dword to an open file. Returns true if OK, false if a file i/o error occurred.
 int Write_dword_le(FILE *file, dword dw);
 
+/// Reads a 16-bit Big-Endian word from an open file. Returns true if OK, false if a file i/o error occurred.
 int Read_word_be(FILE *file, word *dest);
+/// Writes a 16-bit Big-Endian word to an open file. Returns true if OK, false if a file i/o error occurred.
 int Write_word_be(FILE *file, word w);
+/// Reads a 32-bit Big-Endian dword from an open file. Returns true if OK, false if a file i/o error occurred.
 int Read_dword_be(FILE *file, dword *dest);
+/// Writes a 32-bit Big-Endian dword to an open file. Returns true if OK, false if a file i/o error occurred.
 int Write_dword_be(FILE *file, dword dw);
 
+/// Extracts the filename part from a full file name.
 void Extract_filename(char *dest, const char *source);
+/// Extracts the directory from a full file name.
 void Extract_path(char *dest, const char *source);
 
+/// Finds the rightmost path separator in a full filename. Used to separate directory from file.
 char * Find_last_slash(const char * str);
 
 #if defined(__WIN32__)
@@ -49,18 +80,17 @@ char * Find_last_slash(const char * str);
   #define PATH_SEPARATOR "/"
 #endif
 
-// Taille de fichier, en octets
+/// Size of a file, in bytes. Returns 0 in case of error.
 int File_length(const char *fname);
 
-// Taille de fichier, en octets
+/// Size of a file, in bytes. Takes an open file as argument, returns 0 in case of error.
 int File_length_file(FILE * file);
 
-//   Détermine si un file passé en paramètre existe ou non dans le
+/// Returns true if a file passed as a parameter exists in the current directory.
-// répertoire courant.
 int File_exists(char * fname);
-//   Détermine si un répertoire passé en paramètre existe ou non dans le
+
-// répertoire courant.
+/// Returns true if a directory passed as a parameter exists in the current directory.
 int  Directory_exists(char * directory);
 
-// Scans a directory, calls Callback for each file in it,
+/// Scans a directory, calls Callback for each file in it,
 void For_each_file(const char * directory_name, void Callback(const char *));

keyboard.c

@@ -21,6 +21,7 @@
 #include <string.h>
 #include <ctype.h>
 #include "global.h"
+#include "keyboard.h"
 
 // Table de correspondance des scancode de clavier IBM PC AT vers
 // les symboles de touches SDL (sym).

keyboard.h

@@ -20,8 +20,26 @@
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 
+//////////////////////////////////////////////////////////////////////////////
+///@file keyboard.h
+/// Functions to convert bewteen the SDL key formats and the keycode we use
+/// in grafx2.
+/// The keycode we're using is generalized to handle mouse and joystick shortcuts
+/// as well. The format can be broken down as:
+/// - 0x0000 + a number between 0 and SDLK_LAST (about 324) : the SDL "sym" key number.
+/// - 0x0000 + SDLK_LAST+1: Mouse middle button.
+/// - 0x0000 + SDLK_LAST+2: Mouse wheel up.
+/// - 0x0000 + SDLK_LAST+3: Mouse wheel down.
+/// - 0x0000 + SDLK_LAST+4+B : Joystick button number "B", starting at B=0.
+/// - 0x0800 + a number between 0 and 0x7FF: The scancode key number, for keys which have no "sym", such as keys from multimedia keyboards, and "fn" and "Thinkpad" key for a laptop.
+/// Add 0x1000 for the Shift modifier MOD_SHIFT
+/// Add 0x2000 for the Control modifier ::MOD_CONTROL
+/// Add 0x4000 for the Alt modifier ::MOD_ALT
+//////////////////////////////////////////////////////////////////////////////
+
 /*!
   Convert an SDL keysym to an ANSI/ASCII character.
+  This is used to type text and numeric values in input boxes.
   @param keysym SDL symbol to convert
 */
 word Keysym_to_ANSI(SDL_keysym keysym);
@@ -30,12 +48,15 @@ word Keysym_to_ANSI(SDL_keysym keysym);
   Convert an SDL keysym to an internal keycode number.
   This is needed because SDL tends to split the information across the unicode sym, the regular sym, and the raw keycode.
   We also need to differenciate 1 (keypad) and 1 (regular keyboard), and some other things.
+  See the notice at the beginning of keyboard.h for the format of a keycode.
   @param keysym SDL symbol to convert
 */
 word Keysym_to_keycode(SDL_keysym keysym);
 
 /*!
-    Helper function to convert between SDL system and old coding for keycodes. This is needed because some SDL keycode are actually unicode and won't fit in 8 bits.
+    Helper function to convert between SDL system and the old coding for PC keycodes.
+    This is only used to convert configuration files from the DOS version of 
+    Grafx2, where keyboard codes are in in the IBM PC AT form.
   @param scancode Scancode to convert
 */
 word Key_for_scancode(word scancode);
@@ -48,6 +69,7 @@ const char * Key_name(word Key);
 
 /*!
   Gets the modifiers in our format from the SDL_Mod information.
+  Returns a combination of ::MOD_SHIFT, ::MOD_ALT, ::MOD_CONTROL
   @param mod SDL modifiers state
 */
 word Key_modifiers(SDLMod mod);

loadsave.h

@@ -18,6 +18,11 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+//////////////////////////////////////////////////////////////////////////////
+///@file loadsave.h
+/// Saving and loading different picture formats.
+/// Also handles showing the preview in fileselectors.
+//////////////////////////////////////////////////////////////////////////////
 
 void Pixel_load_in_current_screen(word x_pos,word y_pos,byte color);
 void Pixel_load_in_preview      (word x_pos,word y_pos,byte color);
@@ -25,20 +30,30 @@ void Pixel_load_in_brush       (word x_pos,word y_pos,byte color);
 
 void filename_complet(char * filename, byte is_colorix_format);
 
+///
+/// High-level picture loading function.
+/// Handles loading an image or a brush, or previewing only.
+/// @param image true if the fileselector is the one for loading images (not brush)
 void Load_image(byte image);
+///
+/// High-level picture saving function.
+/// @param image true if the image should be saved (instead of the brush)
 void Save_image(byte image);
 
+/// Data for an image file format.
 typedef struct {
-  char *Extension;
+  char *Extension;  ///< Three-letter file extension
-  Func_action Test;
+  Func_action Test; ///< Function which tests if the file is of this format
-  Func_action Load;
+  Func_action Load; ///< Function which loads an image of this format
-  Func_action Save;
+  Func_action Save; ///< Function which saves an image of this format
-  byte Backup_done; // Le format enregistre toute l'image, on la considère à jour.
+  byte Backup_done; ///< Boolean, true if this format saves all the image, and considers it backed up. Set false for formats which only save the palette.
-  byte Comment; // Le format de fichier autorise un commentaire.
+  byte Comment;     ///< This file format allows a text comment
 } T_Format;
 
-// Tableau des formats connus
+/// Array of the known file formats
 extern T_Format File_formats[NB_KNOWN_FORMATS];
 
-// Fonction de sauvegarde en cas de probleme
+///
+/// Function which attempts to save backups of the images (main and spare),
+/// called in case of SIGSEGV. 
 void Image_emergency_backup(void);

misc.h

@@ -18,10 +18,12 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
-void Effacer_ecran_courant(void);
+//////////////////////////////////////////////////////////////////////////////
-void Copier_ecran_sur_brouillon(void);
+///@file misc.h
+/// Miscellanous unsorted functions.
+//////////////////////////////////////////////////////////////////////////////
+
 void Copy_image_to_brush(short start_x,short start_y,short Brush_width,short Brush_height,word image_width);
-void Permuter_dans_l_image_les_couleurs(byte color_1,byte color_2);
 void Remap_general_lowlevel(byte * conversion_table,byte * buffer,short width,short height,short buffer_width);
 void Scroll_picture(short x_offset,short y_offset);
 void Set_mouse_video_mode_number(void);

mountlist.h

@@ -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 mountlist.h
+/// A function to enumerate the mounting points in the filesystem.
+/// Used to display them in fileselectors.
+//////////////////////////////////////////////////////////////////////////////
+
 #ifndef MOUNTLIST_H_
 # define MOUNTLIST_H_
 

op_c.h

@@ -18,6 +18,14 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file op_c.h
+/// Color reduction and color conversion (24b->8b, RGB<->HSL).
+/// This is called op_c because half of the process was originally 
+/// coded in op_asm, in assembler.
+//////////////////////////////////////////////////////////////////////////////
+
 #ifndef _OP_C_H_
 #define _OP_C_H_
 

operatio.h

@@ -18,8 +18,17 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file operatio.h
+/// Code for the operations, ie all drawing tools.
+//////////////////////////////////////////////////////////////////////////////
+
+/// Do some housekeeping before starting work on a operation.
 void Start_operation_stack(word new_operation);
+/// Put a value on ::Operation_stack
 void Operation_push(short value);
+/// Take a value off ::Operation_stack
 void Operation_pop(short * value);
 
 //////////////////////////////////////////////////// OPERATION_CONTINUOUS_DRAW

pages.h

@@ -18,6 +18,12 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file pages.h
+/// Handler for the Undo/Redo system.
+//////////////////////////////////////////////////////////////////////////////
+
 #ifndef _PAGES_H_
 #define _PAGES_H_
 

palette.c

@@ -35,6 +35,7 @@
 #include "op_c.h"
 #include "windows.h"
 #include "input.h"
+#include "palette.h"
 
 byte Palette_view_is_RGB = 1; // Indique si on est en HSL ou en RGB
 

palette.h

@@ -18,14 +18,22 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+//////////////////////////////////////////////////////////////////////////////
+///@file palette.h
+/// Palette screen, and some palette-related high-level functions.
+//////////////////////////////////////////////////////////////////////////////
+
+/// Open the palette menu and handles everything inside it.
 void Button_Palette(void);
+/// Open the secondary palette menu and handles it.
 void Button_Secondary_palette(void);
 
-// Choose the number of graduations for RGB components, from 2 to 256.
+/// Choose the number of graduations for RGB components, from 2 to 256.
 void Set_palette_RGB_scale(int);
 
-// Scale a component (R, G or B) according to the current RGB graduations
+///
-// The resulting range is [0-255]
+/// Scale a component (R, G or B) according to the current RGB graduations.
+/// Returns the resulting value, in the [0-255] range.
 byte Round_palette_component(byte comp);
 
 /*!

pxdouble.c

@@ -27,6 +27,7 @@
 #include "global.h"
 #include "sdlscreen.h"
 #include "misc.h"
+#include "pxdouble.h"
 #include "pxwide.h" // for Display_transparent_line_on_screen_wide()
 
 #define ZOOMX 2

pxdouble.h

@@ -19,6 +19,12 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file pxdouble.h
+/// Renderer for double pixels (2x2).
+//////////////////////////////////////////////////////////////////////////////
+
 #include "struct.h"
 
   void Pixel_double                      (word x,word y,byte color);

pxsimple.c

@@ -27,6 +27,7 @@
 #include "global.h"
 #include "sdlscreen.h"
 #include "misc.h"
+#include "pxsimple.h"
 
 void Pixel_simple (word x,word y,byte color)
 /* Affiche un pixel de la color aux coords x;y à l'écran */

pxsimple.h

@@ -19,6 +19,12 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file pxsimple.h
+/// Renderer for simple pixels (1x1). This is the normal one.
+//////////////////////////////////////////////////////////////////////////////
+
 #include "struct.h"
 
   void Pixel_simple                      (word x,word y,byte color);

pxtall.c

@@ -27,6 +27,7 @@
 #include "global.h"
 #include "sdlscreen.h"
 #include "misc.h"
+#include "pxtall.h"
 #include "pxsimple.h"
 
 void Pixel_tall (word x,word y,byte color)

pxtall.h

@@ -19,6 +19,12 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file pxtall.h
+/// Renderer for tall pixels (1x2).
+//////////////////////////////////////////////////////////////////////////////
+
 #include "struct.h"
 
   void Pixel_tall                        (word x,word y,byte color);

pxwide.c

@@ -27,6 +27,7 @@
 #include "global.h"
 #include "sdlscreen.h"
 #include "misc.h"
+#include "pxwide.h"
 
 void Pixel_wide (word x,word y,byte color)
 /* Affiche un pixel de la color aux coords x;y à l'écran */

pxwide.h

@@ -19,6 +19,12 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file pxwide.h
+/// Renderer for wide pixels (2x1).
+//////////////////////////////////////////////////////////////////////////////
+
 #include "struct.h"
 
   void Pixel_wide                      (word x,word y,byte color);

readini.c

@@ -27,6 +27,7 @@
 #include "const.h"
 #include "global.h"
 #include "misc.h"
+#include "readini.h"
 
 void Load_INI_clear_string(char * str)
 {

readini.h

@@ -18,6 +18,12 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file readini.h
+/// Reading settings in gfx2.ini
+//////////////////////////////////////////////////////////////////////////////
+
 int Load_INI(T_Config * conf);
 int Load_INI_seek_pattern(char * buffer,char * pattern);
 void Load_INI_clear_string(char * str);

readline.h

@@ -19,21 +19,28 @@
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 
-byte Readline(word x_pos,word y_pos,char * str,byte visible_size,byte input_type);
+//////////////////////////////////////////////////////////////////////////////
-// Paramètres:
+///@file readline.h
-//   x_pos, y_pos    : Coordonnées de la saisie dans la fenêtre
+/// Text input functions.
-//   str          : Chaîne recevant la saisie (et contenant éventuellement une valeur initiale)
+//////////////////////////////////////////////////////////////////////////////
-//   visible_size : Nombre de caractères logeant dans la zone de saisie
-//   input_type     : 0=Chaîne, 1=Nombre, 2=Nom de fichier (255 caractères réels)
-// Sortie:
-//   0: Sortie par annulation (Esc.) / 1: sortie par acceptation (Return)
 
+///
+/// Lets the user input a line of text, exit by Esc or Return.
+/// @param x_pos        Coordinates of input, in window coordinates before scaling.
+/// @param y_pos        Coordinates of input, in window coordinates before scaling.
+/// @param str          The original string value (will be modified, unless user cancels.
+/// @param visible_size Number of characters visible and editable.
+/// @param input_type   0=string, 1=number, 2=filename (255 editable characters)
+/// @return             0 if user cancelled (esc), 1 if accepted (return)
+byte Readline(word x_pos,word y_pos,char * str,byte visible_size,byte input_type);
+
+///
+/// Lets the user input a line of text, exit by Esc or Return.
+/// @param x_pos        Coordinates of input, in window coordinates before scaling.
+/// @param y_pos        Coordinates of input, in window coordinates before scaling.
+/// @param str          The original string value (will be modified, unless user cancels.
+/// @param visible_size Number of characters visible.
+/// @param max_size     Number of characters editable.
+/// @param input_type   0=string, 1=number, 2=filename (255 editable characters)
+/// @return             0 if user cancelled (esc), 1 if accepted (return)
 byte Readline_ex(word x_pos,word y_pos,char * str,byte visible_size,byte max_size, byte input_type);
-// Paramètres:
-//   x_pos, y_pos    : Coordonnées de la saisie dans la fenêtre
-//   str          : Chaîne recevant la saisie (et contenant éventuellement une valeur initiale)
-//   visible_size : Nombre de caractères logeant dans la zone de saisie
-//   max_size     : Nombre de caractères logeant dans la zone de saisie
-//   input_type     : 0=Chaîne, 1=Nombre, 2=Nom de fichier (255 caractères réels)
-// Sortie:
-//   0: Sortie par annulation (Esc.) / 1: sortie par acceptation (Return)

realpath.h

@@ -1,6 +1,36 @@
+/*  Grafx2 - The Ultimate 256-color bitmap paint program
+
+    Copyright 2008 Adrien Destugues
+
+    Grafx2 is free software; you can redistribute it and/or
+    modify it under the terms of the GNU General Public License
+    as published by the Free Software Foundation; version 2
+    of the License.
+
+    Grafx2 is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with Grafx2; if not, see <http://www.gnu.org/licenses/> or
+    write to the Free Software Foundation, Inc.,
+    59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+*/
+
+//////////////////////////////////////////////////////////////////////////////
+///@file realpath.h
+/// Implementation of realpath() that is portable on all our platforms.
+//////////////////////////////////////////////////////////////////////////////
+
 #ifndef _REALPATH_H
 #define _REALPATH_H
 
+///
+/// Makes an absolute filename, resolving symbolic links etc.
+/// @param _path         Input path
+/// @param resolved_path Output path, allocated by caller
+/// @return              (points to resolved_path)
 char *Realpath(const char *_path, char *resolved_path);
 
 #endif

saveini.c

@@ -29,6 +29,7 @@
 #include "io.h"
 #include "errors.h"
 #include "misc.h"
+#include "saveini.h"
 
 int Save_INI_reach_group(FILE * old_file,FILE * new_file,char * buffer,char * group)
 {

saveini.h

@@ -18,4 +18,10 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file saveini.h
+/// Saving settings in gfx2.ini
+//////////////////////////////////////////////////////////////////////////////
+
 int Save_INI(T_Config * conf);

sdlscreen.h

@@ -19,6 +19,12 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file sdlscreen.h
+/// Screen update (refresh) system, and some SDL-specific graphic functions.
+//////////////////////////////////////////////////////////////////////////////
+
 #ifndef SDLSCREEN_H_INCLUDED
 #define SDLSCREEN_H_INCLUDED
 

setup.c

@@ -39,6 +39,7 @@
 
 #include "struct.h"
 #include "io.h"
+#include "setup.h"
 
 int Create_ConfigDirectory(char * config_dir)
 {

setup.h

@@ -21,7 +21,36 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file setup.h
+/// Functions that determine where grafx2 is running, finds its data, and
+/// reads and writes configuration files.
+//////////////////////////////////////////////////////////////////////////////
+
+///
+/// Determine which directory contains the executable.
+/// - IN: Main's argv[0], some platforms need it, some don't.
+/// - OUT: Write into program_dir. Trailing / or \ is kept.
+/// Note : in fact this is only used to check for the datafiles and fonts in this same directory.
 void Set_program_directory(const char * argv0,char * program_dir);
+
+///
+/// Determine which directory contains the read-only data.
+/// IN: The directory containing the executable
+/// OUT: Write into data_dir. Trailing / or \ is kept.
 void Set_data_directory(const char * program_dir, char * data_dir);
+
+///
+/// Determine which directory should store the user's configuration.
+/// For most Unix and Windows platforms:
+/// If a config file already exists in program_dir, it will return it in priority
+/// (Useful for development, and possibly for upgrading from DOS version)
+/// If the standard directory doesn't exist yet, this function will attempt 
+/// to create it ($(HOME)/.grafx2, or %APPDATA%\\GrafX2)
+/// If it cannot be created, this function will return the executable's
+/// own directory.
+/// IN: The directory containing the executable
+/// OUT: Write into config_dir. Trailing / or \ is kept.
 void Set_config_directory(const char * program_dir, char * config_dir);
   

shade.c

@@ -30,6 +30,7 @@
 #include "sdlscreen.h"
 #include "windows.h"
 #include "input.h"
+#include "shade.h"
 
 void Button_Shade_mode(void)
 {

shade.h

@@ -18,6 +18,12 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+//////////////////////////////////////////////////////////////////////////////
+///@file shade.h
+/// Screens for Shade and Quick-shade settings.
+//////////////////////////////////////////////////////////////////////////////
+
+
 #ifndef SHADE_H_INCLUDED
 #define SHADE_H_INCLUDED
 

special.c

@@ -26,6 +26,7 @@
 #include "graph.h"
 #include "engine.h"
 #include "windows.h"
+#include "special.h"
 
 
 

special.h

@@ -18,6 +18,13 @@
     write to the Free Software Foundation, Inc.,
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
+
+//////////////////////////////////////////////////////////////////////////////
+///@file special.h
+/// Editor functions that can be hooked to a keyboard shortcut, but don't have
+/// a menu button associated to them.
+//////////////////////////////////////////////////////////////////////////////
+
 void Set_paintbrush_size(int width, int height);
 void Smaller_paintbrush(void);
 void Bigger_paintbrush(void);

text.h

@@ -20,19 +20,37 @@
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 
-// Initialisation à faire une fois au début du programme
+//////////////////////////////////////////////////////////////////////////////
+///@file text.h
+/// Functions related to rendering text as a brush, using TrueType or SFont.
+//////////////////////////////////////////////////////////////////////////////
+
+/// Initialization of text settings, needs to be called once on program startup.
 void Init_text(void);
-// Informe si texte.c a été compilé avec l'option de support TrueType ou pas.
+/// Returns true if text.c was compiled with TrueType support.
 int TrueType_is_supported(void);
-// Ajout d'une fonte à la liste.
+/// Add a new font to the list to propose to the user.
-void Add_font(char *name);
+void Add_font(const char *name);
-// Crée une brosse à partir des paramètres de texte demandés.
+///
+/// Creates a brush, from the parameters given:
+/// @param str         The text to render
+/// @param font_number The index of the font to use. Pass 0 for the first font you declared with ::Add_font(), 1 for the second etc.
+/// @param size        The size in points (unused for bitmap fonts)
+/// @param antialias   Boolean, true to use antialiasing in TrueType
+/// @param bold        Boolean, true to use bold rendering in TrueType
+/// @param italic      Boolean, true to use italic rendering in TrueType
+/// @param width       Returns the width of the created brush, in pixels.
+/// @param height      Returns the height of the created brush, in pixels.
+/// Returns true on success.
 byte *Render_text(const char *str, int font_number, int size, int antialias, int bold, int italic, int *width, int *height);
-// Trouve le libellé d'affichage d'une fonte par son numéro
+
+/// Finds a label to display for a font declared with ::Add_font().
 char * Font_label(int index);
-// Trouve le nom d'une fonte par son numéro
+/// Finds the filename of a font declared with ::Add_font().
 char * Font_name(int index);
-// Vérifie si une fonte donnée est TrueType
+/// Returns true if the font of this number is TrueType, false if it's a SFont bitmap.
 char * TrueType_font(int index);
-// Nombre de fontes déclarées
+///
+/// Number of fonts declared with a series of ::Add_font(). This is public for
+/// convenience, but functionaly it is read-only.
 extern int Nb_fonts;

windows.h

@@ -19,6 +19,11 @@
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 
+//////////////////////////////////////////////////////////////////////////////
+///@file windows.h
+/// Graphical interface management functions (windows, menu, cursor)
+//////////////////////////////////////////////////////////////////////////////
+
 #ifndef __WINDOWS_H_
 #define __WINDOWS_H_