* src/:

+ Doxygenated public functions.

src/bitmap.c

@@ -120,6 +120,19 @@ static void mask2shift(unsigned int mask, int *right, int *left)
     *left = 12 - lshift;
 }
 
+/**
+ * \brief Create an internal bitmap object.
+ *
+ * \param bitmap The bitmap depth in bits per pixel.
+ * \param w The bitmap width in pixels.
+ * \param h The bitmap height in pixels.
+ * \param pitch The bitmap pitch in bytes.
+ * \param rmask The bitmask for red values.
+ * \param gmask The bitmask for green values.
+ * \param bmask The bitmask for blue values.
+ * \param amask The bitmask for alpha values.
+ * \return A bitmap object or NULL upon error.
+ */
 struct caca_bitmap *caca_create_bitmap(unsigned int bpp, unsigned int w,
                                        unsigned int h, unsigned int pitch,
                                        unsigned int rmask, unsigned int gmask,
@@ -174,6 +187,16 @@ struct caca_bitmap *caca_create_bitmap(unsigned int bpp, unsigned int w,
     return bitmap;
 }
 
+/**
+ * \brief Set the palette of an 8bpp bitmap object.
+ *
+ * \param bpp The bitmap object.
+ * \param red An array of 256 red values.
+ * \param green An array of 256 green values.
+ * \param blue An array of 256 blue values.
+ * \param alpha An array of 256 alpha values.
+ * \return void
+ */
 void caca_set_bitmap_palette(struct caca_bitmap *bitmap,
                              unsigned int red[], unsigned int green[],
                              unsigned int blue[], unsigned int alpha[])
@@ -204,6 +227,12 @@ void caca_set_bitmap_palette(struct caca_bitmap *bitmap,
     bitmap->has_alpha = has_alpha;
 }
 
+/**
+ * \brief Free the memory associated with a bitmap.
+ *
+ * \param bitmap The bitmap object to be freed.
+ * \return void
+ */
 void caca_free_bitmap(struct caca_bitmap *bitmap)
 {
     if(!bitmap)
@@ -298,6 +327,17 @@ static void rgb2hsv_default(int r, int g, int b, int *hue, int *sat, int *val)
     }
 }
 
+/**
+ * \brief Draw a bitmap on the screen.
+ *
+ * \param x1 X coordinate of the upper-left corner of the drawing area.
+ * \param y1 Y coordinate of the upper-left corner of the drawing area.
+ * \param x2 X coordinate of the lower-right corner of the drawing area.
+ * \param y2 Y coordinate of the lower-right corner of the drawing area.
+ * \param bitmap The bitmap object to be drawn.
+ * \param pixels A pointer to the bitmap's pixels.
+ * \return void
+ */
 void caca_draw_bitmap(int x1, int y1, int x2, int y2,
                       const struct caca_bitmap *bitmap, void *pixels)
 {

src/box.c

@@ -34,6 +34,16 @@
 #include "caca.h"
 #include "caca_internals.h"
 
+/**
+ * \brief Draw a box on the screen using the given character.
+ *
+ * \param x1 X coordinate of the upper-left corner of the box.
+ * \param y1 Y coordinate of the upper-left corner of the box.
+ * \param x2 X coordinate of the lower-right corner of the box.
+ * \param y2 Y coordinate of the lower-right corner of the box.
+ * \param c Character to draw the box outline with.
+ * \return void
+ */
 void caca_draw_box(int x1, int y1, int x2, int y2, char c)
 {
     caca_draw_line(x1, y1, x1, y2, c);
@@ -42,6 +52,15 @@ void caca_draw_box(int x1, int y1, int x2, int y2, char c)
     caca_draw_line(x2, y1, x1, y1, c);
 }
 
+/**
+ * \brief Draw a thin box on the screen.
+ *
+ * \param x1 X coordinate of the upper-left corner of the box.
+ * \param y1 Y coordinate of the upper-left corner of the box.
+ * \param x2 X coordinate of the lower-right corner of the box.
+ * \param y2 Y coordinate of the lower-right corner of the box.
+ * \return void
+ */
 void caca_draw_thin_box(int x1, int y1, int x2, int y2)
 {
     int x, y, xmax, ymax;
@@ -95,6 +114,16 @@ void caca_draw_thin_box(int x1, int y1, int x2, int y2)
         caca_putchar(x2, y2, '\'');
 }
 
+/**
+ * \brief Fill a box on the screen using the given character.
+ *
+ * \param x1 X coordinate of the upper-left corner of the box.
+ * \param y1 Y coordinate of the upper-left corner of the box.
+ * \param x2 X coordinate of the lower-right corner of the box.
+ * \param y2 Y coordinate of the lower-right corner of the box.
+ * \param c Character to fill the box with.
+ * \return void
+ */
 void caca_fill_box(int x1, int y1, int x2, int y2, char c)
 {
     int x, y, xmax, ymax;

src/caca.c

@@ -57,6 +57,11 @@ static void caca_init_terminal(void);
 static mmask_t oldmask;
 #endif
 
+/**
+ * \brief Initialise libcaca.
+ *
+ * \return 0 upon success, a non-zero value if an error occurs.
+ */
 int caca_init(void)
 {
 #if defined(USE_NCURSES)
@@ -125,16 +130,32 @@ int caca_init(void)
     return 0;
 }
 
+/**
+ * \brief Get the screen width.
+ *
+ * \return The screen width, in character cells.
+ */
 unsigned int caca_get_width(void)
 {
     return _caca_width;
 }
 
+/**
+ * \brief Get the screen height.
+ *
+ * \return The screen height, in character cells.
+ */
 unsigned int caca_get_height(void)
 {
     return _caca_height;
 }
 
+/**
+ * \brief Translate a colour value into its name.
+ *
+ * \param color The colour value.
+ * \return A static string containing the colour's name.
+ */
 const char *caca_get_color_name(enum caca_color color)
 {
     static const char *color_names[] =
@@ -163,6 +184,12 @@ const char *caca_get_color_name(enum caca_color color)
     return color_names[color];
 }
 
+/**
+ * \brief Get the current value of a feature.
+ *
+ * \param feature The requested feature.
+ * \return The current value of the feature.
+ */
 enum caca_feature caca_get_feature(enum caca_feature feature)
 {
     switch(feature)
@@ -179,6 +206,12 @@ enum caca_feature caca_get_feature(enum caca_feature feature)
     }
 }
 
+/**
+ * \brief Set a feature.
+ *
+ * \param feature The wanted feature.
+ * \return void
+ */
 void caca_set_feature(enum caca_feature feature)
 {
     switch(feature)
@@ -212,6 +245,12 @@ void caca_set_feature(enum caca_feature feature)
     }
 }
 
+/**
+ * \brief Translate a feature value into its name.
+ *
+ * \param feature The feature value.
+ * \return A static string containing the feature's name.
+ */
 const char *caca_get_feature_name(enum caca_feature feature)
 {
     switch(feature)
@@ -232,6 +271,11 @@ const char *caca_get_feature_name(enum caca_feature feature)
     }
 }
 
+/**
+ * \brief Uninitialise libcaca.
+ *
+ * \return void
+ */
 void caca_end(void)
 {
     _caca_end_graphics();

src/caca.h

@@ -226,9 +226,9 @@ void caca_clear(void);
  * Graphics primitives
  */
 void caca_draw_line(int, int, int, int, char);
-void caca_draw_polyline(const int[], const int[], int, char);
+void caca_draw_polyline(const int x[], const int y[], int, char);
 void caca_draw_thin_line(int, int, int, int);
-void caca_draw_thin_polyline(const int[], const int[], int);
+void caca_draw_thin_polyline(const int x[], const int y[], int);
 
 void caca_draw_circle(int, int, int, char);
 void caca_draw_ellipse(int, int, int, int, char);
@@ -270,8 +270,9 @@ struct caca_bitmap *caca_create_bitmap(unsigned int, unsigned int,
                                        unsigned int, unsigned int,
                                        unsigned int, unsigned int,
                                        unsigned int, unsigned int);
-void caca_set_bitmap_palette(struct caca_bitmap *, unsigned int[],
-                             unsigned int[], unsigned int[], unsigned int[]);
+void caca_set_bitmap_palette(struct caca_bitmap *,
+                             unsigned int r[], unsigned int g[],
+                             unsigned int b[], unsigned int a[]);
 void caca_draw_bitmap(int, int, int, int, const struct caca_bitmap *, void *);
 void caca_free_bitmap(struct caca_bitmap *);
 

src/conic.c

@@ -43,6 +43,15 @@ typedef unsigned char uint8_t;
 
 static void ellipsepoints(int, int, int, int, char);
 
+/**
+ * \brief Draw a circle on the screen using the given character.
+ *
+ * \param x Center X coordinate.
+ * \param y Center Y coordinate.
+ * \param r Circle radius.
+ * \param c Character to draw the circle outline with.
+ * \return void
+ */
 void caca_draw_circle(int x, int y, int r, char c)
 {
     int test, dx, dy;
@@ -57,6 +66,16 @@ void caca_draw_circle(int x, int y, int r, char c)
     }
 }
 
+/**
+ * \brief Fill an ellipse on the screen using the given character.
+ *
+ * \param xo Center X coordinate.
+ * \param yo Center Y coordinate.
+ * \param a Ellipse X radius.
+ * \param b Ellipse Y radius.
+ * \param c Character to fill the ellipse with.
+ * \return void
+ */
 void caca_fill_ellipse(int xo, int yo, int a, int b, char c)
 {
     int d2;
@@ -102,6 +121,16 @@ void caca_fill_ellipse(int xo, int yo, int a, int b, char c)
     }
 }
 
+/**
+ * \brief Draw an ellipse on the screen using the given character.
+ *
+ * \param xo Center X coordinate.
+ * \param yo Center Y coordinate.
+ * \param a Ellipse X radius.
+ * \param b Ellipse Y radius.
+ * \param c Character to draw the ellipse outline with.
+ * \return void
+ */
 void caca_draw_ellipse(int xo, int yo, int a, int b, char c)
 {
     int d2;
@@ -144,6 +173,15 @@ void caca_draw_ellipse(int xo, int yo, int a, int b, char c)
     }
 }
 
+/**
+ * \brief Draw a thin ellipse on the screen.
+ *
+ * \param xo Center X coordinate.
+ * \param yo Center Y coordinate.
+ * \param a Ellipse X radius.
+ * \param b Ellipse Y radius.
+ * \return void
+ */
 void caca_draw_thin_ellipse(int xo, int yo, int a, int b)
 {
     /* FIXME: this is not correct */

src/graphics.c

@@ -92,6 +92,13 @@ static unsigned int _caca_rendertime;
 static enum caca_color _caca_fgcolor = CACA_COLOR_LIGHTGRAY;
 static enum caca_color _caca_bgcolor = CACA_COLOR_BLACK;
 
+/**
+ * \brief Set the default colour pair.
+ *
+ * \param fgcolor The desired foreground colour.
+ * \param bgcolor The desired background colour.
+ * \return void
+ */
 void caca_set_color(enum caca_color fgcolor, enum caca_color bgcolor)
 {
     if(fgcolor < 0 || fgcolor > 15 || bgcolor < 0 || bgcolor > 15)
@@ -111,16 +118,34 @@ void caca_set_color(enum caca_color fgcolor, enum caca_color bgcolor)
 #endif
 }
 
+/**
+ * \brief Get the current foreground colour.
+ *
+ * \return The current foreground colour.
+ */
 enum caca_color caca_get_fg_color(void)
 {
     return _caca_fgcolor;
 }
 
+/**
+ * \brief Get the current background colour.
+ *
+ * \return The current background colour.
+ */
 enum caca_color caca_get_bg_color(void)
 {
     return _caca_bgcolor;
 }
 
+/**
+ * \brief Print a character at given coordinates.
+ *
+ * \param x The X coordinate of the character.
+ * \param y The Y coordinate of the character.
+ * \param c The character to print.
+ * \return void
+ */
 void caca_putchar(int x, int y, char c)
 {
 #if defined(USE_CONIO)
@@ -147,6 +172,14 @@ void caca_putchar(int x, int y, char c)
 #endif
 }
 
+/**
+ * \brief Print a string at given coordinates.
+ *
+ * \param x The X coordinate of the string.
+ * \param y The Y coordinate of the string.
+ * \param s The string to print.
+ * \return void
+ */
 void caca_putstr(int x, int y, const char *s)
 {
     unsigned int len;
@@ -192,6 +225,15 @@ void caca_putstr(int x, int y, const char *s)
 #endif
 }
 
+/**
+ * \brief Format a string at given coordinates.
+ *
+ * \param x The X coordinate of the string.
+ * \param y The Y coordinate of the string.
+ * \param format The format string to print.
+ * \param ... Arguments to the format string.
+ * \return void
+ */
 void caca_printf(int x, int y, const char *format, ...)
 {
     char tmp[BUFSIZ];
@@ -219,6 +261,11 @@ void caca_printf(int x, int y, const char *format, ...)
         free(buf);
 }
 
+/**
+ * \brief Clear the screen.
+ *
+ * \return void
+ */
 void caca_clear(void)
 {
     enum caca_color oldfg = caca_get_fg_color();
@@ -418,11 +465,22 @@ int _caca_end_graphics(void)
     return 0;
 }
 
+/**
+ * \brief Set the refresh delay.
+ *
+ * \param usec The refresh delay in microseconds.
+ * \return void
+ */
 void caca_set_delay(unsigned int usec)
 {
     _caca_delay = usec;
 }
 
+/**
+ * \brief Get the average rendering time.
+ *
+ * \return The render time in microseconds.
+ */
 unsigned int caca_get_rendertime(void)
 {
     return _caca_rendertime;
@@ -448,6 +506,11 @@ static unsigned int _caca_getticks(void)
     return ticks;
 }
 
+/**
+ * \brief Flush pending changes and redraw the screen.
+ *
+ * \return void
+ */
 void caca_refresh(void)
 {
 #define IDLE_USEC 10000

src/io.c

@@ -53,6 +53,11 @@ static unsigned int _read_key(void);
 static unsigned int keybuf[KEY_BUFLEN + 1]; /* zero-terminated */
 static int keys = 0;
 
+/**
+ * \brief Get the next mouse or keyboard input event.
+ *
+ * \return The next event in the queue, or 0 if no event is pending.
+ */
 unsigned int caca_get_event(void)
 {
     unsigned int event = 0;

src/line.c

@@ -76,6 +76,18 @@ void caca_draw_line(int x1, int y1, int x2, int y2, char c)
     clip_line(&s);
 }
 
+/**
+ * \brief Draw a polyline on the screen using the given character and
+ *        coordinate arrays. The first and last points are not connected,
+ *        so in order to draw a polygon you need to specify the starting
+ *        point at the end of the list as well.
+ *
+ * \param x Array of X coordinates. Must have \p n + 1 elements.
+ * \param y Array of Y coordinates. Must have \p n + 1 elements.
+ * \param n Number of lines to draw.
+ * \param c Character to draw the lines with.
+ * \return void
+ */
 void caca_draw_polyline(const int x[], const int y[], int n, char c)
 {
     int i;
@@ -113,6 +125,17 @@ void caca_draw_thin_line(int x1, int y1, int x2, int y2)
     clip_line(&s);
 }
 
+/**
+ * \brief Draw a thin polyline on the screen using the given coordinate
+ *        arrays and with ASCII art. The first and last points are not
+ *        connected, so in order to draw a polygon you need to specify the
+ *        starting point at the end of the list as well.
+ *
+ * \param x Array of X coordinates. Must have \p n + 1 elements.
+ * \param y Array of Y coordinates. Must have \p n + 1 elements.
+ * \param n Number of lines to draw.
+ * \return void
+ */
 void caca_draw_thin_polyline(const int x[], const int y[], int n)
 {
     int i;
@@ -195,7 +218,7 @@ static void clip_line(struct line* s)
  *
  * \param x X coordinate of the point.
  * \param y Y coordinate of the point.
- * \return b The clipping bits for the given point.
+ * \return The clipping bits for the given point.
  */
 static uint8_t clip_bits(int x, int y)
 {

src/math.c

@@ -34,11 +34,25 @@
 #include "caca.h"
 #include "caca_internals.h"
 
+/**
+ * \brief Generate a random integer within a range.
+ *
+ * \param min The lower bound of the integer range.
+ * \param max The upper bound of the integer range.
+ * \return A random integer comprised between \p min and \p max, inclusive.
+ */
 int caca_rand(int min, int max)
 {
     return min + (int)((1.0*(max-min+1)) * rand() / (RAND_MAX+1.0));
 }
 
+/**
+ * \brief Approximate a square root, using Newton's method to avoid
+ *        costly floating point calculations.
+ *
+ * \param a A positive integer.
+ * \return The approximate square root of \p a.
+ */
 unsigned int caca_sqrt(unsigned int a)
 {
     if(a == 0)

src/sprite.c

@@ -50,6 +50,12 @@ struct caca_sprite
     struct caca_frame *frames;
 };
 
+/**
+ * \brief Allocate a sprite loaded from a file.
+ *
+ * \param file The filename.
+ * \return The sprite, or NULL if an error occured.
+ */
 struct caca_sprite *caca_load_sprite(const char *file)
 {
     char buf[BUFSIZ];
@@ -165,6 +171,12 @@ sprite_alloc_failed:
     return NULL;
 }
 
+/**
+ * \brief Return the number of frames in a sprite.
+ *
+ * \param sprite The sprite.
+ * \return The number of frames.
+ */
 int caca_get_sprite_frames(const struct caca_sprite *sprite)
 {
     if(sprite == NULL)
@@ -173,6 +185,13 @@ int caca_get_sprite_frames(const struct caca_sprite *sprite)
     return sprite->nf;
 }
 
+/**
+ * \brief Return the width of a sprite.
+ *
+ * \param sprite The sprite.
+ * \param f The frame index.
+ * \return The width of the given frame of the sprite.
+ */
 int caca_get_sprite_width(const struct caca_sprite *sprite, int f)
 {
     if(sprite == NULL)
@@ -184,6 +203,13 @@ int caca_get_sprite_width(const struct caca_sprite *sprite, int f)
     return sprite->frames[f].w;
 }
 
+/**
+ * \brief Return the height of a sprite.
+ *
+ * \param sprite The sprite.
+ * \param f The frame index.
+ * \return The height of the given frame of the sprite.
+ */
 int caca_get_sprite_height(const struct caca_sprite *sprite, int f)
 {
     if(sprite == NULL)
@@ -195,6 +221,13 @@ int caca_get_sprite_height(const struct caca_sprite *sprite, int f)
     return sprite->frames[f].h;
 }
 
+/**
+ * \brief Return the X coordinate of a sprite's handle.
+ *
+ * \param sprite The sprite.
+ * \param f The frame index.
+ * \return The X coordinate of the given frame's handle.
+ */
 int caca_get_sprite_dx(const struct caca_sprite *sprite, int f)
 {
     if(sprite == NULL)
@@ -206,6 +239,13 @@ int caca_get_sprite_dx(const struct caca_sprite *sprite, int f)
     return sprite->frames[f].dx;
 }
 
+/**
+ * \brief Return the Y coordinate of a sprite's handle.
+ *
+ * \param sprite The sprite.
+ * \param f The frame index.
+ * \return The Y coordinate of the given frame's handle.
+ */
 int caca_get_sprite_dy(const struct caca_sprite *sprite, int f)
 {
     if(sprite == NULL)
@@ -217,6 +257,16 @@ int caca_get_sprite_dy(const struct caca_sprite *sprite, int f)
     return sprite->frames[f].dy;
 }
 
+/**
+ * \brief Draw a sprite's specific frame at the given coordinates. If the
+ *        frame does not exist, nothing is displayed.
+ *
+ * \param x The X coordinate.
+ * \param y The Y coordinate.
+ * \param sprite The sprite.
+ * \param f The frame index.
+ * \return void
+ */
 void caca_draw_sprite(int x, int y, const struct caca_sprite *sprite, int f)
 {
     int i, j;
@@ -251,6 +301,12 @@ void caca_draw_sprite(int x, int y, const struct caca_sprite *sprite, int f)
     caca_set_color(oldfg, oldbg);
 }
 
+/**
+ * \brief Free the memory associated with a sprite.
+ *
+ * \param sprite The sprite to be freed.
+ * \return void
+ */
 void caca_free_sprite(struct caca_sprite *sprite)
 {
     int i;

src/triangle.c

@@ -34,6 +34,18 @@
 #include "caca.h"
 #include "caca_internals.h"
 
+/**
+ * \brief Draw a triangle on the screen using the given character.
+ *
+ * \param x1 X coordinate of the first point.
+ * \param y1 Y coordinate of the first point.
+ * \param x2 X coordinate of the second point.
+ * \param y2 Y coordinate of the second point.
+ * \param x3 X coordinate of the third point.
+ * \param y3 Y coordinate of the third point.
+ * \param c Character to draw the triangle outline with.
+ * \return void
+ */
 void caca_draw_triangle(int x1, int y1, int x2, int y2, int x3, int y3, char c)
 {
     caca_draw_line(x1, y1, x2, y2, c);
@@ -41,6 +53,17 @@ void caca_draw_triangle(int x1, int y1, int x2, int y2, int x3, int y3, char c)
     caca_draw_line(x3, y3, x1, y1, c);
 }
 
+/**
+ * \brief Draw a thin triangle on the screen.
+ *
+ * \param x1 X coordinate of the first point.
+ * \param y1 Y coordinate of the first point.
+ * \param x2 X coordinate of the second point.
+ * \param y2 Y coordinate of the second point.
+ * \param x3 X coordinate of the third point.
+ * \param y3 Y coordinate of the third point.
+ * \return void
+ */
 void caca_draw_thin_triangle(int x1, int y1, int x2, int y2, int x3, int y3)
 {
     caca_draw_thin_line(x1, y1, x2, y2);
@@ -48,6 +71,18 @@ void caca_draw_thin_triangle(int x1, int y1, int x2, int y2, int x3, int y3)
     caca_draw_thin_line(x3, y3, x1, y1);
 }
 
+/**
+ * \brief Fill a triangle on the screen using the given character.
+ *
+ * \param x1 X coordinate of the first point.
+ * \param y1 Y coordinate of the first point.
+ * \param x2 X coordinate of the second point.
+ * \param y2 Y coordinate of the second point.
+ * \param x3 X coordinate of the third point.
+ * \param y3 Y coordinate of the third point.
+ * \param c Character to fill the triangle with.
+ * \return void
+ */
 void caca_fill_triangle(int x1, int y1, int x2, int y2, int x3, int y3, char c)
 {
     int x, y, xa, xb, xmax, ymax;