* Improved documentation in many places.

caca/caca.c

@@ -98,7 +98,7 @@ caca_t * caca_attach(cucul_t * qq)
  *  libcucul canvas continues to exist and other graphical contexts can be
  *  attached to it afterwards.
  *
- *  \param qq The caca graphical context.
+ *  \param kk The libcaca graphical context.
  */
 void caca_detach(caca_t *kk)
 {

caca/caca.h

@@ -77,6 +77,7 @@
 #ifndef __CACA_H__
 #define __CACA_H__
 
+/** libcaca API version */
 #define CACA_API_VERSION_1
 
 #include <cucul.h>

caca/event.c

@@ -50,9 +50,11 @@ static int _lowlevel_event(caca_t *, struct caca_event *);
  *  if no more events are pending in the queue. A negative value causes the
  *  function to wait indefinitely until a matching event is received.
  *
- * \param event_mask Bitmask of requested events.
- * \param timeout A timeout value in microseconds
- * \return The next matching event in the queue, or 0 if no event is pending.
+ *  \param kk The libcaca graphical context.
+ *  \param event_mask Bitmask of requested events.
+ *  \param timeout A timeout value in microseconds
+ *  \param ev A pointer to a caca_event structure.
+ *  \return The next matching event in the queue, or 0 if no event is pending.
  */
 int caca_get_event(caca_t *kk, unsigned int event_mask,
                    struct caca_event *ev, int timeout)
@@ -106,6 +108,7 @@ int caca_get_event(caca_t *kk, unsigned int event_mask,
  *  drivers are being used, because mouse position is only detected when
  *  the mouse is clicked. Other drivers such as X11 work well.
  *
+ *  \param kk The libcaca graphical context.
  *  \return The X mouse coordinate.
  */
 unsigned int caca_get_mouse_x(caca_t *kk)
@@ -123,6 +126,7 @@ unsigned int caca_get_mouse_x(caca_t *kk)
  *  drivers are being used, because mouse position is only detected when
  *  the mouse is clicked. Other drivers such as X11 work well.
  *
+ *  \param kk The libcaca graphical context.
  *  \return The Y mouse coordinate.
  */
 unsigned int caca_get_mouse_y(caca_t *kk)

caca/graphics.c

@@ -27,6 +27,7 @@
  *  If libcaca runs in a window, try to change its title. This works with
  *  the X11 and Win32 drivers.
  *
+ *  \param kk The libcaca graphical context.
  *  \param title The desired window title.
  *  \return 0 upon success, a non-zero value if an error occurs.
  */
@@ -42,6 +43,7 @@ int caca_set_window_title(caca_t *kk, char const *title)
  *  or if there is no way to know the font size, most drivers will assume a
  *  6x10 font is being used. Note that the units are not necessarily pixels.
  *
+ *  \param kk The libcaca graphical context.
  *  \return The window width.
  */
 unsigned int caca_get_window_width(caca_t *kk)
@@ -56,6 +58,7 @@ unsigned int caca_get_window_width(caca_t *kk)
  *  or if there is no way to know the font size, assume a 6x10 font is being
  *  used. Note that the units are not necessarily pixels.
  *
+ *  \param kk The libcaca graphical context.
  *  \return The window height.
  */
 unsigned int caca_get_window_height(caca_t *kk)
@@ -72,6 +75,7 @@ unsigned int caca_get_window_height(caca_t *kk)
  *  If the argument is zero, constant framerate is disabled. This is the
  *  default behaviour.
  *
+ *  \param kk The libcaca graphical context.
  *  \param usec The refresh delay in microseconds.
  */
 void caca_set_delay(caca_t *kk, unsigned int usec)
@@ -87,6 +91,7 @@ void caca_set_delay(caca_t *kk, unsigned int usec)
  *  rendering time will not be considerably shorter than the requested delay
  *  even if the real rendering time was shorter.
  *
+ *  \param kk The libcaca graphical context.
  *  \return The render time in microseconds.
  */
 unsigned int caca_get_rendertime(caca_t *kk)
@@ -105,6 +110,8 @@ unsigned int caca_get_rendertime(caca_t *kk)
  *  calls to caca_display() are within a time range shorter than the value
  *  set with caca_set_delay(), the second call will wait a bit before
  *  performing the screen refresh.
+ *
+ *  \param kk The libcaca graphical context.
  */
 void caca_display(caca_t *kk)
 {
@@ -146,6 +153,7 @@ void caca_display(caca_t *kk)
  *  This function shows or hides the mouse pointer, for devices that
  *  support it.
  *
+ *  \param kk The libcaca graphical context.
  *  \param flag 0 hides the pointer, 1 shows the system's default pointer
  *              (usually an arrow). Other values are reserved for future use.
  */

cucul/box.c

@@ -24,15 +24,15 @@
 #include "cucul.h"
 #include "cucul_internals.h"
 
-/**
- * \brief Draw a box on the screen using the given character.
+/** \brief Draw a box on the canvas 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 str UTF-8 string containing the character to use to draw the box.
- * \return void
+ *  \param qq The handle to the libcucul canvas.
+ *  \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 str UTF-8 string containing the character to use to draw the box.
+ *  \return void
  */
 void cucul_draw_box(cucul_t *qq, int x1, int y1, int x2, int y2, 
                     char const *str)
@@ -43,14 +43,14 @@ void cucul_draw_box(cucul_t *qq, int x1, int y1, int x2, int y2,
     cucul_draw_line(qq, x2, y1, x1, y1, str);
 }
 
-/**
- * \brief Draw a thin box on the screen.
+/** \brief Draw a thin box on the canvas.
  *
- * \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
+ *  \param qq The handle to the libcucul canvas.
+ *  \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 cucul_draw_thin_box(cucul_t *qq, int x1, int y1, int x2, int y2)
 {
@@ -105,15 +105,15 @@ void cucul_draw_thin_box(cucul_t *qq, int x1, int y1, int x2, int y2)
         _cucul_putchar32(qq, x2, y2, (uint32_t)'\'');
 }
 
-/**
- * \brief Fill a box on the screen using the given character.
+/** \brief Fill a box on the canvas 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 str UTF-8 string containing the character to fill the box with.
- * \return void
+ *  \param qq The handle to the libcucul canvas.
+ *  \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 str UTF-8 string containing the character to fill the box with.
+ *  \return void
  */
 void cucul_fill_box(cucul_t *qq, int x1, int y1, int x2, int y2,
                     char const *str)

cucul/canvas.c

@@ -43,6 +43,7 @@
  *  caca_printf() and graphical primitive functions such as caca_draw_line()
  *  will use these colour pairs.
  *
+ *  \param qq A handle to the libcucul canvas.
  *  \param fgcolor The requested foreground colour.
  *  \param bgcolor The requested background colour.
  */
@@ -60,11 +61,12 @@ void cucul_set_color(cucul_t *qq, unsigned int fgcolor, unsigned int bgcolor)
  *
  *  This function prints an ASCII character at the given coordinates, using
  *  the default foreground and background values. If the coordinates are
- *  outside the screen boundaries, nothing is printed. If the character
+ *  outside the canvas boundaries, nothing is printed. If the character
  *  value is a non-printable character or is outside the ASCII range, it is
  *  replaced with a space. To print a sequence of bytes forming an UTF-8
  *  character, use cucul_putstr() instead.
  *
+ *  \param qq A handle to the libcucul canvas.
  *  \param x X coordinate.
  *  \param y Y coordinate.
  *  \param c The character to print.
@@ -86,9 +88,10 @@ void cucul_putchar(cucul_t *qq, int x, int y, char c)
  *
  *  This function prints an UTF-8 string at the given coordinates, using the
  *  default foreground and background values. The coordinates may be outside
- *  the screen boundaries (eg. a negative Y coordinate) and the string will
+ *  the canvas boundaries (eg. a negative Y coordinate) and the string will
  *  be cropped accordingly if it is too long.
  *
+ *  \param qq A handle to the libcucul canvas.
  *  \param x X coordinate.
  *  \param y Y coordinate.
  *  \param s The string to print.
@@ -128,14 +131,15 @@ void cucul_putstr(cucul_t *qq, int x, int y, char const *s)
     }
 }
 
-/** \brief Format a string.
+/** \brief Print a formated string.
  *
  *  This function formats a string at the given coordinates, using the
  *  default foreground and background values. The coordinates may be outside
- *  the screen boundaries (eg. a negative Y coordinate) and the string will
+ *  the canvas boundaries (eg. a negative Y coordinate) and the string will
  *  be cropped accordingly if it is too long. The syntax of the format
  *  string is the same as for the C printf() function.
  *
+ *  \param qq A handle to the libcucul canvas.
  *  \param x X coordinate.
  *  \param y Y coordinate.
  *  \param format The format string to print.
@@ -168,9 +172,9 @@ void cucul_printf(cucul_t *qq, int x, int y, char const *format, ...)
         free(buf);
 }
 
-/** \brief Clear the screen.
+/** \brief Clear the canvas.
  *
- *  This function clears the screen using a black background.
+ *  This function clears the canvas using a black background.
  */
 void cucul_clear(cucul_t *qq)
 {

cucul/conic.c

@@ -27,14 +27,15 @@
 
 static void ellipsepoints(cucul_t *, int, int, int, int, uint32_t);
 
-/**
- * \brief Draw a circle on the screen using the given character.
+/** \brief Draw a circle on the canvas 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
+ *  \param qq The handle to the libcucul canvas.
+ *  \param x Center X coordinate.
+ *  \param y Center Y coordinate.
+ *  \param r Circle radius.
+ *  \param str UTF-8 string representing the character that should be used
+ *         to draw the circle outline.
+ *  \return void
  */
 void cucul_draw_circle(cucul_t *qq, int x, int y, int r, char const *str)
 {
@@ -51,15 +52,16 @@ void cucul_draw_circle(cucul_t *qq, int x, int y, int r, char const *str)
     }
 }
 
-/**
- * \brief Fill an ellipse on the screen using the given character.
+/** \brief Fill an ellipse on the canvas 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
+ *  \param qq The handle to the libcucul canvas.
+ *  \param xo Center X coordinate.
+ *  \param yo Center Y coordinate.
+ *  \param a Ellipse X radius.
+ *  \param b Ellipse Y radius.
+ *  \param str UTF-8 string representing the character that should be used
+ *         to fill the ellipse.
+ *  \return void
  */
 void cucul_fill_ellipse(cucul_t *qq, int xo, int yo, int a, int b,
                         char const *str)
@@ -107,15 +109,16 @@ void cucul_fill_ellipse(cucul_t *qq, int xo, int yo, int a, int b,
     }
 }
 
-/**
- * \brief Draw an ellipse on the screen using the given character.
+/** \brief Draw an ellipse on the canvas 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
+ *  \param qq The handle to the libcucul canvas.
+ *  \param xo Center X coordinate.
+ *  \param yo Center Y coordinate.
+ *  \param a Ellipse X radius.
+ *  \param b Ellipse Y radius.
+ *  \param str UTF-8 string representing the character that should be used
+ *         to draw the ellipse outline.
+ *  \return void
  */
 void cucul_draw_ellipse(cucul_t *qq, int xo, int yo, int a, int b,
                         char const *str)
@@ -161,14 +164,14 @@ void cucul_draw_ellipse(cucul_t *qq, int xo, int yo, int a, int b,
     }
 }
 
-/**
- * \brief Draw a thin ellipse on the screen.
+/** \brief Draw a thin ellipse on the canvas.
  *
- * \param xo Center X coordinate.
- * \param yo Center Y coordinate.
- * \param a Ellipse X radius.
- * \param b Ellipse Y radius.
- * \return void
+ *  \param qq The handle to the libcucul canvas.
+ *  \param xo Center X coordinate.
+ *  \param yo Center Y coordinate.
+ *  \param a Ellipse X radius.
+ *  \param b Ellipse Y radius.
+ *  \return void
  */
 void cucul_draw_thin_ellipse(cucul_t *qq, int xo, int yo, int a, int b)
 {

cucul/cucul.c

@@ -39,7 +39,7 @@
  *
  *  \param width The desired canvas width
  *  \param height The desired canvas height
- *  \return 0 upon success, a non-zero value if an error occurs.
+ *  \return A libcucul canvas handle upon success, NULL if an error occurred.
  */
 cucul_t * cucul_create(unsigned int width, unsigned int height)
 {
@@ -134,6 +134,7 @@ cucul_t *cucul_load(void *data, unsigned int size)
  *  resize through user interaction. See the caca_event() documentation
  *  for more about this.
  *
+ *  \param qq A libcucul canvas
  *  \param width The desired canvas width
  *  \param height The desired canvas height
  */
@@ -149,6 +150,7 @@ void cucul_set_size(cucul_t *qq, unsigned int width, unsigned int height)
  *
  *  This function returns the current canvas width, in character cells.
  *
+ *  \param qq A libcucul canvas
  *  \return The canvas width.
  */
 unsigned int cucul_get_width(cucul_t *qq)
@@ -160,6 +162,7 @@ unsigned int cucul_get_width(cucul_t *qq)
  *
  *  This function returns the current canvas height, in character cells.
  *
+ *  \param qq A libcucul canvas
  *  \return The canvas height.
  */
 unsigned int cucul_get_height(cucul_t *qq)
@@ -208,6 +211,8 @@ char const *cucul_get_color_name(unsigned int color)
  *  This function frees all resources allocated by cucul_create(). After
  *  cucul_free() has been called, no other \e libcucul functions may be used
  *  unless a new call to cucul_create() is done.
+ *
+ *  \param qq A libcucul canvas
  */
 void cucul_free(cucul_t *qq)
 {
@@ -249,15 +254,14 @@ struct cucul_buffer * cucul_create_export(cucul_t *qq, char const *format)
     return ex;
 }
 
-/**
- * \brief Get available export formats
+/** \brief Get available export formats
  *
- * Return a list of available export formats. The list is a NULL-terminated
- * array of strings, interleaving a string containing the internal value for
- * the export format, to be used with \e cucul_create_export(), and a string
- * containing the natural language description for that export format.
+ *  Return a list of available export formats. The list is a NULL-terminated
+ *  array of strings, interleaving a string containing the internal value for
+ *  the export format, to be used with \e cucul_create_export(), and a string
+ *  containing the natural language description for that export format.
  *
- * \return An array of strings.
+ *  \return An array of strings.
  */
 char const * const * cucul_get_export_list(void)
 {

cucul/cucul.h

@@ -23,6 +23,7 @@
 #ifndef __CUCUL_H__
 #define __CUCUL_H__
 
+/** libcucul API version */
 #define CUCUL_API_VERSION_1
 
 #ifdef __cplusplus
@@ -144,12 +145,12 @@ unsigned int cucul_sqrt(unsigned int);
  *
  *  @{ */
 struct cucul_sprite;
-struct cucul_sprite * cucul_load_sprite(cucul_t *, char const *);
-int cucul_get_sprite_frames(cucul_t *, struct cucul_sprite const *);
-int cucul_get_sprite_width(cucul_t *, struct cucul_sprite const *, int);
-int cucul_get_sprite_height(cucul_t *, struct cucul_sprite const *, int);
-int cucul_get_sprite_dx(cucul_t *, struct cucul_sprite const *, int);
-int cucul_get_sprite_dy(cucul_t *, struct cucul_sprite const *, int);
+struct cucul_sprite * cucul_load_sprite(char const *);
+int cucul_get_sprite_frames(struct cucul_sprite const *);
+int cucul_get_sprite_width(struct cucul_sprite const *, int);
+int cucul_get_sprite_height(struct cucul_sprite const *, int);
+int cucul_get_sprite_dx(struct cucul_sprite const *, int);
+int cucul_get_sprite_dy(struct cucul_sprite const *, int);
 void cucul_draw_sprite(cucul_t *, int, int, struct cucul_sprite const *, int);
 void cucul_free_sprite(struct cucul_sprite *);
 /*  @} */

cucul/dither.c

@@ -227,24 +227,23 @@ static inline void rgb2hsv_default(int r, int g, int b,
     }
 }
 
-/**
- * \brief Create an internal dither object.
+/** \brief Create an internal dither object.
  *
- * Create a dither structure from its coordinates (depth, width, height and
- * pitch) and pixel mask values. If the depth is 8 bits per pixel, the mask
- * values are ignored and the colour palette should be set using the
- * cucul_set_dither_palette() function. For depths greater than 8 bits per
- * pixel, a zero alpha mask causes the alpha values to be ignored.
+ *  Create a dither structure from its coordinates (depth, width, height and
+ *  pitch) and pixel mask values. If the depth is 8 bits per pixel, the mask
+ *  values are ignored and the colour palette should be set using the
+ *  cucul_set_dither_palette() function. For depths greater than 8 bits per
+ *  pixel, a zero alpha mask causes the alpha values to be ignored.
  *
- * \param bpp Bitmap depth in bits per pixel.
- * \param w Bitmap width in pixels.
- * \param h Bitmap height in pixels.
- * \param pitch Bitmap pitch in bytes.
- * \param rmask Bitmask for red values.
- * \param gmask Bitmask for green values.
- * \param bmask Bitmask for blue values.
- * \param amask Bitmask for alpha values.
- * \return Dither object, or NULL upon error.
+ *  \param bpp Bitmap depth in bits per pixel.
+ *  \param w Bitmap width in pixels.
+ *  \param h Bitmap height in pixels.
+ *  \param pitch Bitmap pitch in bytes.
+ *  \param rmask Bitmask for red values.
+ *  \param gmask Bitmask for green values.
+ *  \param bmask Bitmask for blue values.
+ *  \param amask Bitmask for alpha values.
+ *  \return Dither object, or NULL upon error.
  */
 struct cucul_dither *cucul_create_dither(unsigned int bpp, unsigned int w,
                                          unsigned int h, unsigned int pitch,
@@ -320,17 +319,16 @@ struct cucul_dither *cucul_create_dither(unsigned int bpp, unsigned int w,
     return d;
 }
 
-/**
- * \brief Set the palette of an 8bpp dither object.
+/** \brief Set the palette of an 8bpp dither object.
  *
- * Set the palette of an 8 bits per pixel bitmap. Values should be between
- * 0 and 4095 (0xfff).
+ *  Set the palette of an 8 bits per pixel bitmap. Values should be between
+ *  0 and 4095 (0xfff).
  *
- * \param dither Dither object.
- * \param red Array of 256 red values.
- * \param green Array of 256 green values.
- * \param blue Array of 256 blue values.
- * \param alpha Array of 256 alpha values.
+ *  \param d Dither object.
+ *  \param red Array of 256 red values.
+ *  \param green Array of 256 green values.
+ *  \param blue Array of 256 blue values.
+ *  \param alpha Array of 256 alpha values.
  */
 void cucul_set_dither_palette(struct cucul_dither *d,
                               unsigned int red[], unsigned int green[],
@@ -362,26 +360,24 @@ void cucul_set_dither_palette(struct cucul_dither *d,
     d->has_alpha = has_alpha;
 }
 
-/**
- * \brief Set the brightness of a dither object.
+/** \brief Set the brightness of a dither object.
  *
- * Set the brightness of dither.
+ *  Set the brightness of dither.
  *
- * \param dither Dither object.
- * \param brightness brightness value.
+ *  \param d Dither object.
+ *  \param brightness brightness value.
  */
 void cucul_set_dither_brightness(struct cucul_dither *d, float brightness)
 {
     /* FIXME */
 }
 
-/**
- * \brief Set the gamma of a dither object.
+/** \brief Set the gamma of a dither object.
  *
- * Set the gamma of dither.
+ *  Set the gamma of dither.
  *
- * \param dither Dither object.
- * \param gamma Gamma value.
+ *  \param d Dither object.
+ *  \param gamma Gamma value.
  */
 void cucul_set_dither_gamma(struct cucul_dither *d, float gamma)
 {
@@ -399,46 +395,43 @@ void cucul_set_dither_gamma(struct cucul_dither *d, float gamma)
         d->gammatab[i] = 4096.0 * gammapow((float)i / 4096.0, 1.0 / gamma);
 }
 
-/**
- * \brief Invert colors of dither
+/** \brief Invert colors of dither
  *
- * Invert colors of dither
+ *  Invert colors of dither
  *
- * \param dither Dither object.
- * \param value 0 for normal behaviour, 1 for invert
+ *  \param d Dither object.
+ *  \param value 0 for normal behaviour, 1 for invert
  */
 void cucul_set_dither_invert(struct cucul_dither *d, int value)
 {
     d->invert = value ? 1 : 0;
 }
 
-/**
- * \brief Set the contrast of a dither object.
+/** \brief Set the contrast of a dither object.
  *
- * Set the contrast of dither.
+ *  Set the contrast of dither.
  *
- * \param dither Dither object.
- * \param contrast contrast value.
+ *  \param d Dither object.
+ *  \param contrast contrast value.
  */
 void cucul_set_dither_contrast(struct cucul_dither *d, float contrast)
 {
     /* FIXME */
 }
 
-/**
- * \brief Set dither antialiasing
+/** \brief Set dither antialiasing
  *
- * Tell the renderer whether to antialias the dither. Antialiasing smoothen
- * the rendered image and avoids the commonly seen staircase effect.
+ *  Tell the renderer whether to antialias the dither. Antialiasing smoothen
+ *  the rendered image and avoids the commonly seen staircase effect.
  *
- * \li \e "none": no antialiasing.
+ *  \li \e "none": no antialiasing.
  *
- * \li \e "prefilter": simple prefilter antialiasing. This is the default
- *     value.
+ *  \li \e "prefilter": simple prefilter antialiasing. This is the default
+ *      value.
  *
- * \param dither Dither object.
- * \param str A string describing the antialiasing method that will be used
- *        for the dithering.
+ *  \param d Dither object.
+ *  \param str A string describing the antialiasing method that will be used
+ *         for the dithering.
  */
 void cucul_set_dither_antialias(struct cucul_dither *d, char const *str)
 {
@@ -448,17 +441,16 @@ void cucul_set_dither_antialias(struct cucul_dither *d, char const *str)
         d->antialias = 1;
 }
 
-/**
- * \brief Get available antialiasing methods
+/** \brief Get available antialiasing methods
  *
- * Return a list of available antialiasing methods for a given dither. The
- * list is a NULL-terminated array of strings, interleaving a string
- * containing the internal value for the antialiasing method to be used with
- * \e cucul_set_dither_antialias(), and a string containing the natural
- * language description for that antialiasing method.
+ *  Return a list of available antialiasing methods for a given dither. The
+ *  list is a NULL-terminated array of strings, interleaving a string
+ *  containing the internal value for the antialiasing method to be used with
+ *  \e cucul_set_dither_antialias(), and a string containing the natural
+ *  language description for that antialiasing method.
  *
- * \param dither Dither object.
- * \return An array of strings.
+ *  \param d Dither object.
+ *  \return An array of strings.
  */
 char const * const *
     cucul_get_dither_antialias_list(struct cucul_dither const *d)
@@ -473,32 +465,31 @@ char const * const *
     return list;
 }
 
-/**
- * \brief Choose colours used for dithering
+/** \brief Choose colours used for dithering
  *
- * Tell the renderer which colours should be used to render the
- * bitmap. Valid values for \e str are:
+ *  Tell the renderer which colours should be used to render the
+ *  bitmap. Valid values for \e str are:
  *
- * \li \e "mono": use light gray on a black background.
+ *  \li \e "mono": use light gray on a black background.
  *
- * \li \e "gray": use white and two shades of gray on a black background.
+ *  \li \e "gray": use white and two shades of gray on a black background.
  *
- * \li \e "8": use the 8 ANSI colours on a black background.
+ *  \li \e "8": use the 8 ANSI colours on a black background.
  *
- * \li \e "16": use the 16 ANSI colours on a black background.
+ *  \li \e "16": use the 16 ANSI colours on a black background.
  *
- * \li \e "fullgray": use black, white and two shades of gray for both the
- *     characters and the background.
+ *  \li \e "fullgray": use black, white and two shades of gray for both the
+ *      characters and the background.
  *
- * \li \e "full8": use the 8 ANSI colours for both the characters and the
- *     background.
+ *  \li \e "full8": use the 8 ANSI colours for both the characters and the
+ *      background.
  *
- * \li \e "full16": use the 16 ANSI colours for both the characters and the
- *     background. This is the default value.
+ *  \li \e "full16": use the 16 ANSI colours for both the characters and the
+ *      background. This is the default value.
  *
- * \param dither Dither object.
- * \param str A string describing the colour set that will be used
- *        for the dithering.
+ *  \param d Dither object.
+ *  \param str A string describing the colour set that will be used
+ *         for the dithering.
  */
 void cucul_set_dither_color(struct cucul_dither *d, char const *str)
 {
@@ -518,17 +509,16 @@ void cucul_set_dither_color(struct cucul_dither *d, char const *str)
         d->color_mode = COLOR_MODE_FULL16;
 }
 
-/**
- * \brief Get available colour modes
+/** \brief Get available colour modes
  *
- * Return a list of available colour modes for a given dither. The list
- * is a NULL-terminated array of strings, interleaving a string containing
- * the internal value for the colour mode, to be used with
- * \e cucul_set_dither_color(), and a string containing the natural
- * language description for that colour mode.
+ *  Return a list of available colour modes for a given dither. The list
+ *  is a NULL-terminated array of strings, interleaving a string containing
+ *  the internal value for the colour mode, to be used with
+ *  \e cucul_set_dither_color(), and a string containing the natural
+ *  language description for that colour mode.
  *
- * \param dither Dither object.
- * \return An array of strings.
+ *  \param d Dither object.
+ *  \return An array of strings.
  */
 char const * const *
     cucul_get_dither_color_list(struct cucul_dither const *d)
@@ -548,24 +538,23 @@ char const * const *
     return list;
 }
 
-/**
- * \brief Choose characters used for dithering
+/** \brief Choose characters used for dithering
  *
- * Tell the renderer which characters should be used to render the
- * dither. Valid values for \e str are:
+ *  Tell the renderer which characters should be used to render the
+ *  dither. Valid values for \e str are:
  *
- * \li \e "ascii": use only ASCII characters. This is the default value.
+ *  \li \e "ascii": use only ASCII characters. This is the default value.
  *
- * \li \e "shades": use Unicode characters "U+2591 LIGHT SHADE", "U+2592
- *     MEDIUM SHADE" and "U+2593 DARK SHADE". These characters are also
- *     present in the CP437 codepage available on DOS and VGA.
+ *  \li \e "shades": use Unicode characters "U+2591 LIGHT SHADE", "U+2592
+ *      MEDIUM SHADE" and "U+2593 DARK SHADE". These characters are also
+ *      present in the CP437 codepage available on DOS and VGA.
  *
- * \li \e "blocks": use Unicode quarter-cell block combinations. These
- *     characters are only found in the Unicode set.
+ *  \li \e "blocks": use Unicode quarter-cell block combinations. These
+ *      characters are only found in the Unicode set.
  *
- * \param dither Dither object.
- * \param str A string describing the characters that need to be used
- *        for the dithering.
+ *  \param d Dither object.
+ *  \param str A string describing the characters that need to be used
+ *         for the dithering.
  */
 void cucul_set_dither_charset(struct cucul_dither *d, char const *str)
 {
@@ -586,17 +575,16 @@ void cucul_set_dither_charset(struct cucul_dither *d, char const *str)
     }
 }
 
-/**
- * \brief Get available dither character sets
+/** \brief Get available dither character sets
  *
- * Return a list of available character sets for a given dither. The list
- * is a NULL-terminated array of strings, interleaving a string containing
- * the internal value for the character set, to be used with
- * \e cucul_set_dither_charset(), and a string containing the natural
- * language description for that character set.
+ *  Return a list of available character sets for a given dither. The list
+ *  is a NULL-terminated array of strings, interleaving a string containing
+ *  the internal value for the character set, to be used with
+ *  \e cucul_set_dither_charset(), and a string containing the natural
+ *  language description for that character set.
  *
- * \param dither Dither object.
- * \return An array of strings.
+ *  \param d Dither object.
+ *  \return An array of strings.
  */
 char const * const *
     cucul_get_dither_charset_list(struct cucul_dither const *d)
@@ -612,28 +600,27 @@ char const * const *
     return list;
 }
 
-/**
- * \brief Set dithering method
+/** \brief Set dithering method
  *
- * Tell the renderer which dithering method should be used. Dithering is
- * necessary because the picture being rendered has usually far more colours
- * than the available palette. Valid values for \e str are:
+ *  Tell the renderer which dithering method should be used. Dithering is
+ *  necessary because the picture being rendered has usually far more colours
+ *  than the available palette. Valid values for \e str are:
  *
- * \li \e "none": no dithering is used, the nearest matching colour is used.
+ *  \li \e "none": no dithering is used, the nearest matching colour is used.
  *
- * \li \e "ordered2": use a 2x2 Bayer matrix for dithering.
+ *  \li \e "ordered2": use a 2x2 Bayer matrix for dithering.
  *
- * \li \e "ordered4": use a 4x4 Bayer matrix for dithering.
+ *  \li \e "ordered4": use a 4x4 Bayer matrix for dithering.
  *
- * \li \e "ordered8": use a 8x8 Bayer matrix for dithering.
+ *  \li \e "ordered8": use a 8x8 Bayer matrix for dithering.
  *
- * \li \e "random": use random dithering.
+ *  \li \e "random": use random dithering.
  *
- * \li \e "fstein": use Floyd-Steinberg dithering. This is the default value.
+ *  \li \e "fstein": use Floyd-Steinberg dithering. This is the default value.
  *
- * \param dither Dither object.
- * \param str A string describing the method that needs to be used
- *        for the dithering.
+ *  \param d Dither object.
+ *  \param str A string describing the method that needs to be used
+ *         for the dithering.
  */
 void cucul_set_dither_mode(struct cucul_dither *d, char const *str)
 {
@@ -675,17 +662,16 @@ void cucul_set_dither_mode(struct cucul_dither *d, char const *str)
     }
 }
 
-/**
- * \brief Get dithering methods
+/** \brief Get dithering methods
  *
- * Return a list of available dithering methods for a given dither. The list
- * is a NULL-terminated array of strings, interleaving a string containing
- * the internal value for the dithering method, to be used with
- * \e cucul_set_dither_dithering(), and a string containing the natural
- * language description for that dithering method.
+ *  Return a list of available dithering methods for a given dither. The list
+ *  is a NULL-terminated array of strings, interleaving a string containing
+ *  the internal value for the dithering method, to be used with
+ *  \e cucul_set_dither_dithering(), and a string containing the natural
+ *  language description for that dithering method.
  *
- * \param dither Dither object.
- * \return An array of strings.
+ *  \param d Dither object.
+ *  \return An array of strings.
  */
 char const * const *
     cucul_get_dither_mode_list(struct cucul_dither const *d)
@@ -704,18 +690,18 @@ char const * const *
     return list;
 }
 
-/**
- * \brief Draw a dither on the screen.
+/** \brief Draw a dither on the screen.
  *
- * Draw a dither at the given coordinates. The dither can be of any size and
- * will be stretched to the text area.
+ *  Draw a dither at the given coordinates. The dither can be of any size and
+ *  will be stretched to the text area.
  *
- * \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 dither Dither object to be drawn.
- * \param pixels Bitmap's pixels.
+ *  \param qq A handle to the libcucul canvas.
+ *  \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 d Dither object to be drawn.
+ *  \param pixels Bitmap's pixels.
  */
 void cucul_dither_bitmap(cucul_t *qq, int x1, int y1, int x2, int y2,
                          struct cucul_dither const *d, void *pixels)
@@ -963,12 +949,11 @@ void cucul_dither_bitmap(cucul_t *qq, int x1, int y1, int x2, int y2,
     free(floyd_steinberg);
 }
 
-/**
- * \brief Free the memory associated with a dither.
+/** \brief Free the memory associated with a dither.
  *
- * Free the memory allocated by cucul_create_dither().
+ *  Free the memory allocated by cucul_create_dither().
  *
- * \param dither Dither object.
+ *  \param d Dither object.
  */
 void cucul_free_dither(struct cucul_dither *d)
 {

cucul/font.c

@@ -34,7 +34,8 @@
 #include "font_mono9.h"
 #include "font_monobold12.h"
 
-/* Helper structure for font loading */
+/* Helper structures for font loading */
+#if !defined(_DOXYGEN_SKIP_ME)
 struct font_header
 {
     uint32_t control_size, data_size;
@@ -64,6 +65,7 @@ struct cucul_font
 
     uint8_t *private;
 };
+#endif
 
 #define DECLARE_UNPACKGLYPH(bpp) \
     static inline void \
@@ -192,13 +194,12 @@ struct cucul_font *cucul_load_font(void const *data, unsigned int size)
     return f;
 }
 
-/**
- * \brief Get available builtin fonts
+/** \brief Get available builtin fonts
  *
- * Return a list of available builtin fonts. The list is a NULL-terminated
- * array of strings.
+ *  Return a list of available builtin fonts. The list is a NULL-terminated
+ *  array of strings.
  *
- * \return An array of strings.
+ *  \return An array of strings.
  */
 char const * const * cucul_get_font_list(void)
 {

cucul/line.c

@@ -40,15 +40,15 @@ static uint8_t clip_bits(cucul_t*, int, int);
 static void draw_solid_line(cucul_t*, struct line*);
 static void draw_thin_line(cucul_t*, struct line*);
 
-/**
- * \brief Draw a line on the screen using the given character.
+/** \brief Draw a line on the canvas 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 str UTF-8 string containing the character to use to draw the line.
- * \return void
+ *  \param qq The handle to the libcucul canvas.
+ *  \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 str UTF-8 string containing the character to use to draw the line.
+ *  \return void
  */
 void cucul_draw_line(cucul_t *qq, int x1, int y1, int x2, int y2,
                      char const *str)
@@ -63,17 +63,19 @@ void cucul_draw_line(cucul_t *qq, int x1, int y1, int x2, int y2,
     clip_line(qq, &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.
+/** \brief Draw a polyline.
  *
- * \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 str UTF-8 string containing the character to use to draw the lines.
- * \return void
+ *  Draw a plyline on the canvas using the given character and coordinate
+ *  arrays. The first and last points are not connected, hence in order to
+ *  draw a polygon you need to specify the starting point at the end of the
+ *  list as well.
+ *
+ *  \param qq The handle to the libcucul canvas.
+ *  \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 str UTF-8 string containing the character to use to draw the lines.
+ *  \return void
  */
 void cucul_draw_polyline(cucul_t *qq, int const x[], int const y[], int n,
                          char const *str)
@@ -93,14 +95,14 @@ void cucul_draw_polyline(cucul_t *qq, int const x[], int const y[], int n,
     }
 }
 
-/**
- * \brief Draw a thin line on the screen, using ASCII art.
+/** \brief Draw a thin line on the canvas, using ASCII art.
  *
- * \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.
- * \return void
+ *  \param qq The handle to the libcucul canvas.
+ *  \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.
+ *  \return void
  */
 void cucul_draw_thin_line(cucul_t *qq, int x1, int y1, int x2, int y2)
 {
@@ -113,16 +115,18 @@ void cucul_draw_thin_line(cucul_t *qq, int x1, int y1, int x2, int y2)
     clip_line(qq, &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.
+/** \brief Draw an ASCII art thin polyline.
+ *
+ *  Draw a thin polyline on the canvas 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
+ *  \param qq The handle to the libcucul canvas.
+ *  \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 cucul_draw_thin_polyline(cucul_t *qq, int const x[], int const y[], int n)
 {
@@ -144,12 +148,7 @@ void cucul_draw_thin_polyline(cucul_t *qq, int const x[], int const y[], int n)
  * XXX: The following functions are local.
  */
 
-/**
- * \brief Generic Cohen-Sutherland line clipping function.
- *
- * \param s a line structure
- * \return void
- */
+/* Generic Cohen-Sutherland line clipping function. */
 static void clip_line(cucul_t *qq, struct line* s)
 {
     uint8_t bits1, bits2;
@@ -201,13 +200,7 @@ static void clip_line(cucul_t *qq, struct line* s)
     clip_line(qq, s);
 }
 
-/**
- * \brief Helper function for clip_line().
- *
- * \param x X coordinate of the point.
- * \param y Y coordinate of the point.
- * \return The clipping bits for the given point.
- */
+/* Helper function for clip_line(). */
 static uint8_t clip_bits(cucul_t *qq, int x, int y)
 {
     uint8_t b = 0;
@@ -225,13 +218,8 @@ static uint8_t clip_bits(cucul_t *qq, int x, int y)
     return b;
 }
 
-/**
- * \brief Solid line drawing function, using Bresenham's mid-point line
- *       scan-conversion algorithm.
- *
- * \param s a line structure
- * \return void
- */
+/* Solid line drawing function, using Bresenham's mid-point line
+ * scan-conversion algorithm. */
 static void draw_solid_line(cucul_t *qq, struct line* s)
 {
     int x1, y1, x2, y2;
@@ -292,13 +280,8 @@ static void draw_solid_line(cucul_t *qq, struct line* s)
     }
 }
 
-/**
- * \brief Thin line drawing function, using Bresenham's mid-point line
- *        scan-conversion algorithm and ASCII art graphics.
- *
- * \param s a line structure
- * \return void
- */
+/* Thin line drawing function, using Bresenham's mid-point line
+ * scan-conversion algorithm and ASCII art graphics. */
 static void draw_thin_line(cucul_t *qq, struct line* s)
 {
     uint32_t charmapx[2], charmapy[2];

cucul/math.c

@@ -24,24 +24,22 @@
 #include "cucul.h"
 #include "cucul_internals.h"
 
-/**
- * \brief Generate a random integer within a range.
+/** \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.
+ *  \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 cucul_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.
+/** \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.
+ *  \param a A positive integer.
+ *  \return The approximate square root of \p a.
  */
 unsigned int cucul_sqrt(unsigned int a)
 {

cucul/sprite.c

@@ -42,13 +42,12 @@ struct cucul_sprite
 };
 #endif
 
-/**
- * \brief Allocate a sprite loaded from a file.
+/** \brief Allocate a sprite loaded from a file.
  *
- * \param file The filename.
- * \return The sprite, or NULL if an error occured.
+ *  \param file The filename.
+ *  \return The sprite, or NULL if an error occured.
  */
-struct cucul_sprite *cucul_load_sprite(cucul_t *qq, char const *file)
+struct cucul_sprite *cucul_load_sprite(char const *file)
 {
     char buf[BUFSIZ];
     struct cucul_sprite *sprite;
@@ -163,13 +162,12 @@ sprite_alloc_failed:
     return NULL;
 }
 
-/**
- * \brief Return the number of frames in a sprite.
+/** \brief Return the number of frames in a sprite.
  *
- * \param sprite The sprite.
- * \return The number of frames.
+ *  \param sprite The sprite.
+ *  \return The number of frames.
  */
-int cucul_get_sprite_frames(cucul_t *qq, struct cucul_sprite const *sprite)
+int cucul_get_sprite_frames(struct cucul_sprite const *sprite)
 {
     if(sprite == NULL)
         return 0;
@@ -177,14 +175,13 @@ int cucul_get_sprite_frames(cucul_t *qq, struct cucul_sprite const *sprite)
     return sprite->nf;
 }
 
-/**
- * \brief Return the width of a sprite.
+/** \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.
+ *  \param sprite The sprite.
+ *  \param f The frame index.
+ *  \return The width of the given frame of the sprite.
  */
-int cucul_get_sprite_width(cucul_t *qq, struct cucul_sprite const *sprite, int f)
+int cucul_get_sprite_width(struct cucul_sprite const *sprite, int f)
 {
     if(sprite == NULL)
         return 0;
@@ -195,14 +192,13 @@ int cucul_get_sprite_width(cucul_t *qq, struct cucul_sprite const *sprite, int f
     return sprite->frames[f].w;
 }
 
-/**
- * \brief Return the height of a sprite.
+/** \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.
+ *  \param sprite The sprite.
+ *  \param f The frame index.
+ *  \return The height of the given frame of the sprite.
  */
-int cucul_get_sprite_height(cucul_t *qq, struct cucul_sprite const *sprite, int f)
+int cucul_get_sprite_height(struct cucul_sprite const *sprite, int f)
 {
     if(sprite == NULL)
         return 0;
@@ -213,14 +209,13 @@ int cucul_get_sprite_height(cucul_t *qq, struct cucul_sprite const *sprite, int
     return sprite->frames[f].h;
 }
 
-/**
- * \brief Return the X coordinate of a sprite's handle.
+/** \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.
+ *  \param sprite The sprite.
+ *  \param f The frame index.
+ *  \return The X coordinate of the given frame's handle.
  */
-int cucul_get_sprite_dx(cucul_t *qq, struct cucul_sprite const *sprite, int f)
+int cucul_get_sprite_dx(struct cucul_sprite const *sprite, int f)
 {
     if(sprite == NULL)
         return 0;
@@ -231,14 +226,13 @@ int cucul_get_sprite_dx(cucul_t *qq, struct cucul_sprite const *sprite, int f)
     return sprite->frames[f].dx;
 }
 
-/**
- * \brief Return the Y coordinate of a sprite's handle.
+/** \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.
+ *  \param sprite The sprite.
+ *  \param f The frame index.
+ *  \return The Y coordinate of the given frame's handle.
  */
-int cucul_get_sprite_dy(cucul_t *qq, struct cucul_sprite const *sprite, int f)
+int cucul_get_sprite_dy(struct cucul_sprite const *sprite, int f)
 {
     if(sprite == NULL)
         return 0;
@@ -249,15 +243,15 @@ int cucul_get_sprite_dy(cucul_t *qq, struct cucul_sprite const *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.
+/** \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
+ *  \param qq A libcucul canvas
+ *  \param x The X coordinate.
+ *  \param y The Y coordinate.
+ *  \param sprite The sprite.
+ *  \param f The frame index.
+ *  \return void
  */
 void cucul_draw_sprite(cucul_t *qq, int x, int y, struct cucul_sprite const *sprite, int f)
 {
@@ -293,11 +287,10 @@ void cucul_draw_sprite(cucul_t *qq, int x, int y, struct cucul_sprite const *spr
     cucul_set_color(qq, oldfg, oldbg);
 }
 
-/**
- * \brief Free the memory associated with a sprite.
+/** \brief Free the memory associated with a sprite.
  *
- * \param sprite The sprite to be freed.
- * \return void
+ *  \param sprite The sprite to be freed.
+ *  \return void
  */
 void cucul_free_sprite(struct cucul_sprite *sprite)
 {

cucul/triangle.c

@@ -24,17 +24,18 @@
 #include "cucul.h"
 #include "cucul_internals.h"
 
-/**
- * \brief Draw a triangle on the screen using the given character.
+/** \brief Draw a triangle on the canvas 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
+ *  \param qq The handle to the libcucul canvas.
+ *  \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 str UTF-8 string representing the character that should be used
+ *         to draw the triangle outline.
+ *  \return void
  */
 void cucul_draw_triangle(cucul_t *qq, int x1, int y1, int x2, int y2,
                          int x3, int y3, char const *str)
@@ -44,16 +45,16 @@ void cucul_draw_triangle(cucul_t *qq, int x1, int y1, int x2, int y2,
     cucul_draw_line(qq, x3, y3, x1, y1, str);
 }
 
-/**
- * \brief Draw a thin triangle on the screen.
+/** \brief Draw a thin triangle on the canvas.
  *
- * \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
+ *  \param qq The handle to the libcucul canvas.
+ *  \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 cucul_draw_thin_triangle(cucul_t *qq, int x1, int y1, int x2, int y2,
                               int x3, int y3)
@@ -63,17 +64,18 @@ void cucul_draw_thin_triangle(cucul_t *qq, int x1, int y1, int x2, int y2,
     cucul_draw_thin_line(qq, x3, y3, x1, y1);
 }
 
-/**
- * \brief Fill a triangle on the screen using the given character.
+/** \brief Fill a triangle on the canvas 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
+ *  \param qq The handle to the libcucul canvas.
+ *  \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 str UTF-8 string representing the character that should be used
+ *         to fill the triangle.
+ *  \return void
  */
 void cucul_fill_triangle(cucul_t *qq, int x1, int y1, int x2, int y2,
                          int x3, int y3, char const *str)