* Start working on the internal code documentation.

src/debug.c

@@ -38,6 +38,10 @@
 
 extern int _zz_debugfd;
 
+/**
+ * Helper macro to write an integer value to a given file descriptor,
+ * either in base 10 or in hexadecimal.
+ */
 #define WRITE_INT(fd, i, base) \
     do \
     { \
@@ -52,6 +56,17 @@ extern int _zz_debugfd;
         write(fd, b + 1, (int)(buf + 127 - b)); \
     } while(0)
 
+/**
+ * Format a string, printf-like, and write the resulting data to zzuf's
+ * debug file descriptor _zz_debugfd. If the debug file descriptor is
+ * still -1, this function does nothing.
+ *
+ * This function's code is roughly equivalent to the following *printf
+ * calls, except it only uses signal-safe functions:
+ *  - fprintf(stderr, "** zzuf debug ** ");
+ *  - vfprintf(stderr, format, args);
+ *  - fprintf(stderr, "\n");
+ */
 void _zz_debug(char const *format, ...)
 {
     static char const *hex2char = "0123456789abcdef";
@@ -65,14 +80,6 @@ void _zz_debug(char const *format, ...)
     saved_errno = errno;
     va_start(args, format);
 
-#if 0
-    /* This function's code is equivalent to the following *printf calls,
-     * except it only uses signal-safe functions */
-    fprintf(stderr, "** zzuf debug ** ");
-    vfprintf(stderr, format, args);
-    fprintf(stderr, "\n");
-#endif
-
     write(_zz_debugfd, "** zzuf debug ** ", 17);
     for(f = format; *f; f++)
     {

src/fd.c

@@ -70,7 +70,7 @@ static int maxfd, nfiles;
 
 /* Create lock. This lock variable is used to disable file descriptor
  * creation wrappers. For instance on Mac OS X, fopen() calls open()
- * and we don’t want open() to do any zzuf-related stuff, fopen() takes
+ * and we don’t want open() to do any zzuf-related stuff: fopen() takes
  * care of everything. */
 static int create_lock = 0;
 

src/libzzuf.c

@@ -54,14 +54,49 @@ void _zz_fini(void) __attribute__((destructor));
 BOOL WINAPI DllMain(HINSTANCE, DWORD, PVOID);
 #endif
 
-/* Global variables */
+/**
+ * Is libzzuf fully initialised?
+ */
 int   _zz_ready    = 0;
+
+/**
+ * The file descriptor used by libzzuf for communication with the main
+ * zzuf program in debug mode. Its value is set by the ZZUF_DEBUG
+ * environment variable.
+ */
 int   _zz_debugfd  = -1;
+
+/**
+ * If set to 1, this boolean variable will prevent the called application
+ * from installing signal handlers that would prevent it from really crashing.
+ * SDL applications often do that when not using SDL_INIT_NOPARACHUTE, for
+ * instance. Its value is set by the ZZUF_SIGNAL environment variable.
+ */
 int   _zz_signal   = 0;
+
+/**
+ * If set to a positive value, this value will indicate the maximum number
+ * of megabytes that the called application will be allowed to allocate. Its
+ * value is set by the ZZUF_MEMORY environment variable.
+ */
 int   _zz_memory   = 0;
+
+/**
+ * If set to 1, this boolean will tell libzzuf to fuzz network file
+ * descriptors, too. Its value is set by the ZZUF_NETWORK environment
+ * variable.
+ */
 int   _zz_network  = 0;
 
-/* Library initialisation shit */
+/**
+ * Library initialisation routine.
+ *
+ * This function reads all configuration variables put by zzuf in the
+ * called process's environment and initialises diversions for the three
+ * main function families: memory functions (initialised very early because
+ * other functions we need such as dlsym() require them), file descriptor
+ * functions and stream functions.
+ */
 void _zz_init(void)
 {
     char *tmp, *tmp2;
@@ -138,7 +173,11 @@ void _zz_init(void)
     debug("libzzuf initialised for PID %li", (long int)getpid());
 }
 
-/* Deinitialisation */
+/**
+ * Library deinitialisation routine.
+ *
+ * Free all the memory allocated by libzzuf during its lifetime.
+ */
 void _zz_fini(void)
 {
     _zz_fd_fini();
@@ -163,3 +202,4 @@ BOOL WINAPI DllMain(HINSTANCE hinst, DWORD reason, PVOID impLoad)
     return TRUE;
 }
 #endif
+