Document file functions and fix a few issues here and there.

caca/caca.h

@@ -66,6 +66,7 @@ typedef struct caca_event caca_event_t;
  *  Colours and styles that can be used with caca_set_attr().
  *
  *  @{ */
+/** \e libcaca colour keyword */
 enum caca_color
 {
     CACA_BLACK =        0x00, /**< The colour index for black. */
@@ -88,6 +89,7 @@ enum caca_color
     CACA_TRANSPARENT =  0x20, /**< The transparent colour. */
 };
 
+/** \e libcaca style keyword */
 enum caca_style
 {
     CACA_BOLD =      0x01, /**< The style mask for bold. */
@@ -127,14 +129,16 @@ enum caca_event_type
  */
 struct caca_event
 {
-    enum caca_event_type type;
+    enum caca_event_type type; /**< The event type. */
     union
     {
         struct { int x, y, button; } mouse;
         struct { int w, h; } resize;
         struct { int ch; uint32_t utf32; char utf8[8]; } key;
-    } data;
+    } data; /**< The event information data */
+#if !defined(_DOXYGEN_SKIP_ME)
     uint8_t padding[16];
+#endif
 };
 
 /** \brief Special key values.
@@ -568,18 +572,18 @@ enum CACA_CONIO_MODE
  */
 struct caca_conio_text_info
 {
-    unsigned char winleft;        /* left window coordinate */
-    unsigned char wintop;         /* top window coordinate */
-    unsigned char winright;       /* right window coordinate */
-    unsigned char winbottom;      /* bottom window coordinate */
-    unsigned char attribute;      /* text attribute */
-    unsigned char normattr;       /* normal attribute */
-    unsigned char currmode;       /* current video mode:
-                                     BW40, BW80, C40, C80, or C4350 */
-    unsigned char screenheight;   /* text screen's height */
-    unsigned char screenwidth;    /* text screen's width */
-    unsigned char curx;           /* x-coordinate in current window */
-    unsigned char cury;           /* y-coordinate in current window */
+    unsigned char winleft;        /**< left window coordinate */
+    unsigned char wintop;         /**< top window coordinate */
+    unsigned char winright;       /**< right window coordinate */
+    unsigned char winbottom;      /**< bottom window coordinate */
+    unsigned char attribute;      /**< text attribute */
+    unsigned char normattr;       /**< normal attribute */
+    unsigned char currmode;       /**< current video mode:
+                                       BW40, BW80, C40, C80, or C4350 */
+    unsigned char screenheight;   /**< text screen's height */
+    unsigned char screenwidth;    /**< text screen's width */
+    unsigned char curx;           /**< x-coordinate in current window */
+    unsigned char cury;           /**< y-coordinate in current window */
 };
 
 /** \brief DOS direct video control */

caca/file.c

@@ -50,6 +50,19 @@ struct caca_file
 };
 #endif
 
+/** \brief Open a file for reading or writing
+ *
+ *  Create a caca file handle for a file. If the file is zipped, it is
+ *  decompressed on the fly.
+ *
+ *  If an error occurs, NULL is returned and \b errno is set accordingly:
+ *  - \c ENOSTS Function not implemented.
+ *  - \c EINVAL File not found or permission denied.
+ *
+ *  \param path The file path
+ *  \param mode The file open mode
+ *  \return A file handle to \e path.
+ */
 caca_file_t *caca_file_open(char const *path, const char *mode)
 {
 #if defined __KERNEL__
@@ -68,6 +81,7 @@ caca_file_t *caca_file_open(char const *path, const char *mode)
     if(!fp->gz)
     {
         free(fp);
+        seterrno(EINVAL);
         return NULL;
     }
 
@@ -108,6 +122,7 @@ caca_file_t *caca_file_open(char const *path, const char *mode)
         {
             free(fp);
             gzclose(fp->gz);
+            seterrno(EINVAL);
             return NULL;
         }
     }
@@ -117,6 +132,7 @@ caca_file_t *caca_file_open(char const *path, const char *mode)
     if(!fp->f)
     {
         free(fp);
+        seterrno(EINVAL);
         return NULL;
     }
 #   endif
@@ -125,6 +141,15 @@ caca_file_t *caca_file_open(char const *path, const char *mode)
 #endif
 }
 
+/** \brief Close a file handle
+ *
+ *  Close and destroy the resources associated with a caca file handle.
+ *
+ *  This function is a wrapper for fclose() or, if available, gzclose().
+ *
+ *  \param fp The file handle
+ *  \return The return value of fclose() or gzclose().
+ */
 int caca_file_close(caca_file_t *fp)
 {
 #if defined __KERNEL__
@@ -143,6 +168,13 @@ int caca_file_close(caca_file_t *fp)
 #endif
 }
 
+/** \brief Return the position in a file handle
+ *
+ *  Return the file handle position, in bytes.
+ *
+ *  \param fp The file handle
+ *  \return The current offset in the file handle.
+ */
 uint64_t caca_file_tell(caca_file_t *fp)
 {
 #if defined __KERNEL__
@@ -157,6 +189,15 @@ uint64_t caca_file_tell(caca_file_t *fp)
 #endif
 }
 
+/** \brief Read data from a file handle
+ *
+ *  Read data from a file handle and copy them into the given buffer.
+ *
+ *  \param fp The file handle
+ *  \param ptr The destination buffer
+ *  \param size The number of bytes to read
+ *  \return The number of bytes read
+ */
 size_t caca_file_read(caca_file_t *fp, void *ptr, size_t size)
 {
 #if defined __KERNEL__
@@ -171,6 +212,15 @@ size_t caca_file_read(caca_file_t *fp, void *ptr, size_t size)
 #endif
 }
 
+/** \brief Write data to a file handle
+ *
+ *  Write the contents of the given buffer to the file handle.
+ *
+ *  \param fp The file handle
+ *  \param ptr The source buffer
+ *  \param size The number of bytes to write
+ *  \return The number of bytes written
+ */
 size_t caca_file_write(caca_file_t *fp, const void *ptr, size_t size)
 {
 #if defined __KERNEL__
@@ -194,6 +244,16 @@ size_t caca_file_write(caca_file_t *fp, const void *ptr, size_t size)
 #endif
 }
 
+/** \brief Read a line from a file handle
+ *
+ *  Read one line of data from a file handle, up to one less than the given
+ *  number of bytes. A trailing zero is appended to the data.
+ *
+ *  \param fp The file handle
+ *  \param s The destination buffer
+ *  \param size The maximum number of bytes to read
+ *  \return The number of bytes read, including the trailing zero
+ */
 char *caca_file_gets(caca_file_t *fp, char *s, int size)
 {
 #if defined __KERNEL__
@@ -228,6 +288,15 @@ char *caca_file_gets(caca_file_t *fp, char *s, int size)
 #endif
 }
 
+/** \brief Tell whether a file handle reached end of file
+ *
+ *  Return the end-of-file status of the file handle.
+ *
+ *  This function is a wrapper for feof() or, if available, gzeof().
+ *
+ *  \param fp The file handle
+ *  \return 1 if EOF was reached, 0 otherwise
+ */
 int caca_file_eof(caca_file_t *fp)
 {
 #if defined __KERNEL__

caca/string.c

@@ -325,7 +325,7 @@ int caca_printf(caca_canvas_t *cv, int x, int y, char const *format, ...)
  *  \param x X coordinate.
  *  \param y Y coordinate.
  *  \param format The format string to print.
- *  \param ap A va_list containting the arguments to the format string.
+ *  \param args A va_list containting the arguments to the format string.
  *  \return The number of cells printed.
  */
 int caca_vprintf(caca_canvas_t *cv, int x, int y, char const *format,

win32/config.h

@@ -80,6 +80,7 @@
 /* #undef USE_CONIO */
 /* #undef USE_GL */
 /* #undef USE_IMLIB2 */
+/* #undef USE_KERNEL */
 /* #undef USE_NCURSES */
 /* #undef USE_PLUGINS */
 /* #undef USE_SLANG */