More function documentation

src/cursor.c

@@ -49,6 +49,11 @@ int no_fancy_cursors = 1;
 int no_fancy_cursors;
 #endif
 
+/**
+ * Set the current cursor shape.
+ *
+ * @param c The cursor shape to use.
+ */
 void do_setcursor(SDL_Cursor * c)
 {
   /* Shut GCC up over the fact that the XBMs are #included within cursor.h
@@ -81,6 +86,11 @@ void do_setcursor(SDL_Cursor * c)
     SDL_SetCursor(c);
 }
 
+/**
+ * Free (deallocate) a cursor.
+ *
+ * @param cursor Pointer to a cursor to free; will be set to point to NULL afterwards.
+ */
 void free_cursor(SDL_Cursor ** cursor)
 {
   if (*cursor)

src/dirwalk.c

@@ -65,8 +65,14 @@
 
 
 
-///////////////// directory walking callers and callbacks //////////////////
+/* Directory walking callers and callbacks */
 
+/**
+ * Callback to invoke when loading fonts
+ *
+ * @param screen Screen surface, for animating progress bar.
+ * FIXME
+ */
 void loadfont_callback(SDL_Surface * screen, const char *restrict const dir,
                        unsigned dirlen, tp_ftw_str * files, unsigned i, const char *restrict const locale)
 {
@@ -253,15 +259,36 @@ void loadfont_callback(SDL_Surface * screen, const char *restrict const dir,
 }
 
 
-// For qsort()
+/**
+ * Callback for comparing filenames
+ *
+ * @param v1 Filename #1
+ * @param v2 Filename #2
+ * @return An integer less than, equal to, or greater than zero if the
+ *   filename of dir entry 'v1' is found, respectively, to be less than,
+ *   to match, or be greater than that of 'v2'.
+ */
 int compare_ftw_str(const void *v1, const void *v2)
 {
   const char *restrict const s1 = ((tp_ftw_str *) v1)->str;
   const char *restrict const s2 = ((tp_ftw_str *) v2)->str;
 
-  return -strcmp(s1, s2);       /* FIXME: Should we try strcasecmp, to group things together despite uppercase/lowercase in filenames (e.g., Jigsaw* vs jigsaw* Starters)??? -bjk 2009.10.11 */
+  return -strcmp(s1, s2);
+  /* FIXME: Should we try strcasecmp, to group things together despite uppercase/lowercase in filenames (e.g., Jigsaw* vs jigsaw* Starters)??? -bjk 2009.10.11 */
 }
 
+
+/**
+ * Process a directory full of files, using a callback function to
+ * deal with the files. (For loading fonts, brushes, and stamps)
+ *
+ * @param screen Screen surface, for updating progress bar.
+ * @param dir Directory to Process
+ * @param dirlen Size of directory to process
+ * @param rsrc Dealing with resources? (FIXME: better explanation)
+ * @param fn Callback function to invoke
+ * @param locale Locale, to pass to callback function when applicable (i.e., for fonts), else NULL
+ */
 void tp_ftw(SDL_Surface * screen, char *restrict const dir, unsigned dirlen,
             int rsrc, void (*fn) (SDL_Surface * screen,
                                   const char *restrict const dir,

src/fonts.c

@@ -161,29 +161,6 @@ static void reliable_read(int fd, void *buf, size_t count);
 #endif
 
 
-/* This doesn't actually ever get used; see load_locale_font()
-   -bjk 2017.10.15 */
-/*
-#ifndef NO_SDLPANGO
-static TuxPaint_Font *try_alternate_font(int size)
-{
-  char str[128];
-  char prefix[64];
-  char *p;
-
-  strcpy(prefix, lang_prefix);
-  if ((p = strrchr(prefix, '_')) != NULL)
-    {
-      *p = 0;
-      snprintf(str, sizeof(str), "%sfonts/locale/%s.ttf", DATA_PREFIX, prefix);
-
-      return TuxPaint_Font_OpenFont("", str, size);
-    }
-  return NULL;
-}
-#endif
-*/
-
 #ifdef NO_SDLPANGO
 TuxPaint_Font *load_locale_font(TuxPaint_Font * fallback, int size)
 {

src/get_fname.c

@@ -57,6 +57,14 @@ const char *datadir;
 //        for caller-provided space, and maybe callee strdup.
 //        That's at most 4 functions per Tux Paint thread.
 
+/**
+ * Construct a filepath, given a filename, and what kind of file
+ * (data file, or saved images?)
+ *
+ * @param name Filaneme
+ * @param kind What kind of file? (DIR_SAVE or DIR_DATA?)
+ * @return Full fillpath
+ */
 char *get_fname(const char *const name, int kind)
 {
   char f[512];

src/i18n.c

@@ -52,6 +52,10 @@
 
 static int langint = LANG_EN;
 
+/* Strings representing each language's ISO 639 (-1 or -2) codes.
+ * Should map to the 'enum' of possible languages ("LANG_xxx")
+ * found in "i18n.h" (where "NUM_LANGS" is found, as the final
+ * entry in the 'enum' list). */
 const char *lang_prefixes[NUM_LANGS] = {
   "ach",
   "af",
@@ -185,7 +189,7 @@ const char *lang_prefixes[NUM_LANGS] = {
 };
 
 
-// languages which don't use the default font
+/* Languages which don't use the default font */
 static int lang_use_own_font[] = {
   LANG_AR,
   LANG_BO,
@@ -203,6 +207,7 @@ static int lang_use_own_font[] = {
   -1
 };
 
+/* Languages which are written right-to-left */
 static int lang_use_right_to_left[] = {
   LANG_AR,
   LANG_FA,
@@ -213,6 +218,7 @@ static int lang_use_right_to_left[] = {
   -1
 };
 
+/* FIXME: */
 static int lang_use_right_to_left_word[] = {
 #ifdef NO_SDLPANGO
   LANG_HE,
@@ -220,6 +226,8 @@ static int lang_use_right_to_left_word[] = {
   -1
 };
 
+/* Languages which require a vertical 'nudge' in
+ * text rendering, and by how much? */
 static int lang_y_nudge[][2] = {
   {LANG_KM, 4},
   {-1, -1}
@@ -234,6 +242,13 @@ const char *lang_prefix, *short_lang_prefix;
 int num_wished_langs = 0;
 w_langs wished_langs[255];
 
+/* Mappings from human-readable language names (found in
+ * config files, or command-line arguments) to the precise
+ * local code to use.  Some locales appear multiple times,
+ * (e.g. "de_DE.UTF-8" is represented by both "german"
+ * (the English name of the language) and "deutsch"
+ * (the German name of the language)).
+ */
 static const language_to_locale_struct language_to_locale_array[] = {
   {"english", "C"},
   {"american-english", "C"},
@@ -422,13 +437,20 @@ static const language_to_locale_struct language_to_locale_array[] = {
   {"zulu", "zu_ZA.UTF-8"}
 };
 
-/* FIXME: All this should REALLY be array-based!!! */
-/* Show available languages: */
+
+/**
+ * Show available languages
+ *
+ * @param exitcode Exit code; also determines whether STDERR or STDOUT used.
+ *   (e.g., is this output of "--lang help" (STDOUT & exit 0),
+ *   or complaint of an inappropriate "--lang" argument (STDERR & exit 1)?)
+ */
 static void show_lang_usage(int exitcode)
 {
   FILE *f = exitcode ? stderr : stdout;
   const char *const prg = "tuxpaint";
 
+  /* FIXME: All this should REALLY be array-based!!! */
   fprintf(f, "\n" "Usage: %s [--lang LANGUAGE]\n" "\n" "LANGUAGE may be one of:\n"
 /* C */ "  english      american-english\n"
 /* ach */ "  acholi       acoli\n"
@@ -564,10 +586,15 @@ static void show_lang_usage(int exitcode)
 }
 
 
-/* FIXME: Add accented characters to the descriptions */
-/* Show available locales: */
+/**
+ * Show available locales as a "usage" output
+ *
+ * @param f File descriptor to write to (e.g., STDOUT or STDERR)
+ * @param prg Program name (e.g., "tuxpaint" or "tuxpaint.exe")
+ */
 static void show_locale_usage(FILE * f, const char *const prg)
 {
+  /* FIXME: Add accented characters to the descriptions */
   fprintf(f,
           "\n"
           "Usage: %s [--locale LOCALE]\n"
@@ -701,13 +728,23 @@ static void show_locale_usage(FILE * f, const char *const prg)
           "  xh_ZA   (Xhosa)\n" "  zam     (Zapoteco-Miahuatlan)\n" "  zu_ZA   (Zulu)\n" "\n", prg);
 }
 
-
+/**
+ * Return the current language
+ *
+ * @return The current language (one of the LANG_xxx enums)
+ */
 int get_current_language(void)
 {
   return langint;
 }
 
-
+/**
+ * Search an array of ints for a given int
+ *
+ * @param l The int to search for
+ * @param array The array of ints to search, terminated by -1
+ * @return 1 if "l" is found in "array", 0 otherwise
+ */
 static int search_int_array(int l, int *array)
 {
   int i;
@@ -721,8 +758,12 @@ static int search_int_array(int l, int *array)
   return 0;
 }
 
-// This is to ensure that iswprint() works beyond ASCII,
-// even if the locale wouldn't normally support that.
+/**
+ * Ensures that iswprint() works beyond ASCII,
+ * even if the locale wouldn't normally support that.
+ * Tries fallback locales until one works.
+ * Emits an error message to STDERR if none work.
+ */
 static void ctype_utf8(void)
 {
 #ifndef _WIN32
@@ -744,7 +785,12 @@ static void ctype_utf8(void)
 #endif
 }
 
-
+/**
+ * For a given language, return its local, or exit with a usage error.
+ *
+ * @param langstr Name of language (e.g., "german")
+ * @return Locale (e.g., "de_DE.UTF-8")
+ */
 static const char *language_to_locale(const char *langstr)
 {
   int i = sizeof language_to_locale_array / sizeof language_to_locale_array[0];
@@ -761,6 +807,12 @@ static const char *language_to_locale(const char *langstr)
   return NULL;
 }
 
+/**
+ * Set language ("langint" global) based on a given locale;
+ * will try a few ways of checking, is case-insensitive, etc.
+ *
+ * @param loc Locale (e.g., "pt_BR.UTF-8", "pt_BR", "pt_br", etc.)
+ */
 static void set_langint_from_locale_string(const char *restrict loc)
 {
   char *baseloc = strdup(loc);
@@ -869,7 +921,7 @@ static void set_langint_from_locale_string(const char *restrict loc)
         }
     }
 
-/* Last resource, we should never arrive here, this check depends
+  /* Last resort, we should never arrive here, this check depends
      on the right order in lang_prefixes[] 
      Languages sharing the same starting letters must be ordered 
      from longest to shortest, like currently are pt_BR and pt */
@@ -899,6 +951,14 @@ static void set_langint_from_locale_string(const char *restrict loc)
 #undef HAVE_SETENV
 #endif
 
+
+/**
+ * Set an environment variable.
+ * (Wrapper for setenv() or putenv(), depending on OS)
+ *
+ * @param name Variable to set
+ * @param value Value to set the variable to
+ */
 static void mysetenv(const char *name, const char *value)
 {
 #ifdef HAVE_SETENV
@@ -913,7 +973,14 @@ static void mysetenv(const char *name, const char *value)
 }
 
 
+/**
+ * Attempt to set Tux Paint's UI language.
+ *
+ * @param loc Locale
+ * @return The Y-nudge value for font rendering in the language.
+ */
 static int set_current_language(const char *restrict locale_choice) MUST_CHECK;
+
 static int set_current_language(const char *restrict loc)
 {
   int i;
@@ -1088,6 +1155,17 @@ static int set_current_language(const char *restrict locale_choice) MUST_CHECK;
   return wished_langs[0].lang_y_nudge;
 }
 
+
+/**
+ * Given a locale (e.g., "de_DE.UTF-8" or a language name (e.g., "german"),
+ * attempt to set Tux Paint's UI language.  Show help, and exit,
+ * if asked (either 'locale' or 'lang' are "help"), or if the
+ * given input is not recognized.
+ *
+ * @param lang Language name (or NULL)
+ * @param locale Locale (or NULL)
+ * @return Y-nudge
+ */
 int setup_i18n(const char *restrict lang, const char *restrict locale)
 {
 #ifdef DEBUG
@@ -1112,6 +1190,9 @@ int setup_i18n(const char *restrict lang, const char *restrict locale)
 }
 
 #ifdef NO_SDLPANGO
+/**
+ * FIXME
+ */
 int smash_i18n(void)
 {
   return set_current_language("C");

src/macos.c

@@ -1,3 +1,6 @@
+/*
+ * FIXME
+ */
 #include <stdlib.h>
 #include "macos.h"
 
@@ -6,6 +9,9 @@
 #define MACOS_GLOBAL_PREFERENCES_PATH "/Library/Application Support/TuxPaint"
 
 
+/**
+ * FIXME
+ */
 const char* macos_fontsPath()
 {
   static char* p = NULL;
@@ -23,6 +29,9 @@ const char* macos_fontsPath()
 }
 
 
+/**
+ * FIXME
+ */
 const char* macos_preferencesPath()
 {
   static char* p = NULL;
@@ -40,9 +49,10 @@ const char* macos_preferencesPath()
 }
 
 
+/**
+ * FIXME
+ */
 const char* macos_globalPreferencesPath()
 {
   return MACOS_GLOBAL_PREFERENCES_PATH;
 }
-
-

src/playsound.c

@@ -33,6 +33,20 @@ int mute;
 int use_sound = 1;
 static int old_sound[4] = { -1, -1, -1, -1 };
 
+/**
+ * Play a sound.
+ *
+ * @param screen Screen surface (for dealing with panning & volume)
+ * @param chan Channel to play on (-1 for first free unused channel)
+ * @param s Which sound to play (integer index of `sounds[]` array)
+ * @param override 1 to override an already-playing sound, 0 otherwise
+ * @param x X coordinate within the screen surface, for left/right panning
+ *   effect; or SNDPOS_LEFT, SNDPOS_CENTER, or SNDPOS_RIGHT for
+ *   far left, center, or far right panning, respectively.
+ * @param y Y coordinate within the screen surface, for volume control
+ *   (low values, near the top of the window, are quieter), or
+ *   SNDDIST_NEAR for full volume
+ */
 void playsound(SDL_Surface * screen, int chan, int s, int override, int x, int y)
 {
 #ifndef NOSOUND

src/progressbar.c

@@ -34,6 +34,12 @@
 SDL_Surface *img_progress;
 int progress_bar_disabled, prog_bar_ctr;
 
+
+/**
+ * Draw & animate (as function is called repeatedly) the progress bar.
+ *
+ * @param screen Screen surface
+ */
 void show_progress_bar(SDL_Surface * screen)
 {
   SDL_Rect dest, src;

src/rgblinear.c

@@ -30,6 +30,13 @@
 #include "rgblinear.h"
 #include "debug.h"
 
+/**
+ * Return sRGB mapping (0-255 byte) of a linear (0.0 to 1.0) value
+ * (see rgblinear.h)
+ *
+ * @param linear Linear (float) value
+ * @return sRGB (byte) value
+ */
 unsigned char linear_to_sRGB(float linear)
 {
   unsigned slot;

src/win32_dirent.c

@@ -35,6 +35,13 @@
   
 #include "win32_dirent.h"
 #include "debug.h"
+
+/**
+ * Open a directory for reading
+ *
+ * @param pSpec Path of directory to open
+ * @return Opened directory, or NULL on failure
+ */
 DIR * opendir(const char *pSpec) 
 {
   char pathname[MAX_PATH + 2];
@@ -46,7 +53,6 @@
   strcat(pathname, "/*");
   pDir->hFind = FindFirstFile(pathname, &pDir->wfd);
   if (pDir->hFind == INVALID_HANDLE_VALUE)
-    
     {
       free(pDir);
       pDir = NULL;
@@ -54,11 +60,24 @@
   return pDir;
 }
 
+/**
+ * Close an opened directory
+ *
+ * @param pDir Opened directory to close.
+ */
 void closedir(DIR * pDir) 
 {
   assert(pDir != NULL);
   free(pDir);
-} struct dirent *readdir(struct DIR *pDir) 
+}
+
+/**
+ * Read an entry from an opened directory.
+ *
+ * @param pDir Opened directory from which to read.
+ * @return The next entry from the directory
+ */
+struct dirent *readdir(struct DIR *pDir) 
 {
   assert(pDir != NULL);
   if (pDir->hFind)
@@ -76,10 +95,30 @@ void closedir(DIR * pDir)
   return NULL;
 }
 
+/**
+ * Callback for sorting directory entries by filenames.
+ *
+ * @param a Directory entry #1
+ * @param b Directory entry #2
+ * @return An integer less than, equal to, or greater than zero if the
+ *   filename of dir entry 'a' is found, respectively, to be less than,
+ *   to match, or be greater than that of 'b'.
+ */
 int alphasort(const void *a, const void *b) 
 {
   return (strcmp((*(const struct dirent **)a)->d_name, (*(const struct dirent **)b)->d_name));
-} static int addToList(int i, struct dirent ***namelist, struct dirent *entry) 
+}
+
+/**
+ * Add directory entry filenames into a list.
+ *
+ * @param i Incoming count of items
+ * @param namelist Pointer to an array of directory entries, which will
+ *   be resized as items are added
+ * @param entry The directory entry to add to 'namelist'
+ * @return New count of items, or -1 on error (e.g., failed malloc())
+ */
+static int addToList(int i, struct dirent ***namelist, struct dirent *entry) 
 {
   int size;
   struct dirent *block;
@@ -96,6 +135,15 @@ int alphasort(const void *a, const void *b)
   return ++i;
 }
 
+/**
+ * Scan a directory
+ *
+ * @param dir Path to the directory to be scanned.
+ * @param namelist Pointer to an array of directory entries, to be filled.
+ * @param select Callback function for selecting items to add to the list.
+ * @param compar Callback for sorting items in the list (via qsort()).
+ * @return Count of items, or -1 on error.
+ */
 int scandir(const char *dir, struct dirent ***namelist, selectCB select, comparCB compar) 
 {
   DIR * pDir;
@@ -108,7 +156,6 @@ int scandir(const char *dir, struct dirent ***namelist, selectCB select, comparC
     return -1;
   count = 0;
   while ((entry = readdir(pDir)) != NULL)
-    
     {
       if (select == NULL || (select != NULL && select(entry)))
         if ((count = addToList(count, namelist, entry)) < 0)
@@ -121,5 +168,3 @@ int scandir(const char *dir, struct dirent ***namelist, selectCB select, comparC
     qsort((void *)(*namelist), (size_t) count, sizeof(struct dirent *), compar);
   return count;
 }
-
-

src/win32_print.c

@@ -37,6 +37,9 @@
 
 static HDC hDCprinter = NULL;
 
+/**
+ * FIXME
+ */
 static SDL_Surface *make24bitDIB(SDL_Surface * surf)
 {
   SDL_PixelFormat pixfmt;
@@ -84,6 +87,9 @@ static SDL_Surface *make24bitDIB(SDL_Surface * surf)
   return surfDIB;
 }
 
+/**
+ * FIXME
+ */
 /* returns 0 if failed */
 static int GetDefaultPrinterStrings(char *device, char *driver, char *output)
 {
@@ -115,6 +121,9 @@ static int GetDefaultPrinterStrings(char *device, char *driver, char *output)
 
 #define dmDeviceNameSize    32
 
+/**
+ * FIXME
+ */
 static HANDLE LoadCustomPrinterHDEVMODE(HWND hWnd, const char *filepath)
 {
   char device[MAX_PATH];
@@ -179,7 +188,9 @@ err_exit:
   return NULL;
 }
 
-
+/**
+ * FIXME
+ */
 static int SaveCustomPrinterHDEVMODE(HWND hWnd, const char *filepath, HANDLE hDevMode)
 {
   FILE *fp = NULL;
@@ -202,6 +213,12 @@ static int SaveCustomPrinterHDEVMODE(HWND hWnd, const char *filepath, HANDLE hDe
   return 0;
 }
 
+/**
+ * Returns whether or not a given file exists.
+ *
+ * @param filepath Path to the file
+ * @return 1 if file exists, 0 otherwise
+ */
 static int FileExists(const char *filepath)
 {
   FILE *fp;
@@ -214,6 +231,10 @@ static int FileExists(const char *filepath)
   return 0;
 }
 
+
+/**
+ * FIXME
+ */
 static int GetCustomPrinterDC(HWND hWnd, const char *printcfg, int show)
 {
   PRINTDLG pd = {
@@ -254,6 +275,9 @@ static int GetCustomPrinterDC(HWND hWnd, const char *printcfg, int show)
 }
 
 
+/**
+ * FIXME
+ */
 static HDC GetDefaultPrinterDC(void)
 {
   char device[MAX_PATH], driver[MAX_PATH], output[MAX_PATH];
@@ -264,6 +288,10 @@ static HDC GetDefaultPrinterDC(void)
   return NULL;
 }
 
+
+/**
+ * FIXME
+ */
 static int GetPrinterDC(HWND hWnd, const char *printcfg, int show)
 {
   hDCprinter = NULL;
@@ -277,6 +305,9 @@ static int GetPrinterDC(HWND hWnd, const char *printcfg, int show)
 }
 
 
+/**
+ * FIXME
+ */
 int IsPrinterAvailable(void)
 {
   return (GetDefaultPrinterStrings(NULL, NULL, NULL) != 0);
@@ -285,6 +316,10 @@ int IsPrinterAvailable(void)
 #define STRETCH_TO_FIT  0
 #define SCALE_TO_FIT    1
 
+
+/**
+ * FIXME
+ */
 const char *SurfacePrint(SDL_Surface * surf, const char *printcfg, int showdialog)
 {
   const char *res = NULL;
@@ -472,6 +507,10 @@ error:
   return res;
 }
 
+
+/**
+ * FIXME
+ */
 /*
   Read access to Windows Registry
 */
@@ -494,8 +533,11 @@ err_exit:
   return HRESULT_FROM_WIN32(res);
 }
 
-/*
-  Removes a single '\' or '/' from end of path 
+/**
+ * Removes a single '\' or '/' from end of path
+ *
+ * @param path Directory path
+ * @return the path argument, contents of which may have been modified
  */
 static char *remove_slash(char *path)
 {
@@ -533,9 +575,12 @@ char *GetDefaultSaveDir(const char *suffix)
   return strdup("userdata");
 }
 
-/*
-  Returns heap string containing system font directory.
-  E.g. 'C:\Windows\Fonts'
+/**
+ * 
+ * Returns heap string containing system font directory.
+ * (e.g. 'C:\Windows\Fonts')
+ *
+ * @return system font dir
  */
 char *GetSystemFontDir(void)
 {
@@ -567,6 +612,12 @@ static char *GetUserTempDir(void)
   return strdup(temp);
 }
 
+/**
+ * Get path of a file in a temp directory
+ *
+ * @param name Filename for temp file
+ * @return full path to the temp file
+ */
 char *get_temp_fname(const char *const name)
 {
   char f[512];
@@ -584,6 +635,9 @@ char *get_temp_fname(const char *const name)
 static HHOOK g_hKeyboardHook = NULL;
 static int g_bWindowActive = 0;
 
+/**
+ * FIXME
+ */
 LRESULT CALLBACK LowLevelKeyboardProc(int nCode, WPARAM wParam, LPARAM lParam)
 {
   int bEatKeystroke = 0;
@@ -607,6 +661,9 @@ LRESULT CALLBACK LowLevelKeyboardProc(int nCode, WPARAM wParam, LPARAM lParam)
   return CallNextHookEx(g_hKeyboardHook, nCode, wParam, lParam);
 }
 
+/**
+ * FIXME
+ */
 int InstallKeyboardHook(void)
 {
   if (g_hKeyboardHook)
@@ -615,6 +672,9 @@ int InstallKeyboardHook(void)
   return g_hKeyboardHook ? 0 : -2;
 }
 
+/**
+ * FIXME
+ */
 int RemoveKeyboardHook(void)
 {
   if (!g_hKeyboardHook)
@@ -624,6 +684,9 @@ int RemoveKeyboardHook(void)
   return 0;
 }
 
+/**
+ * FIXME
+ */
 void SetActivationState(int state)
 {
   g_bWindowActive = state;