* Removed "This function..." constructs from documentation. Fixed a few

documentation errors or imprecisions.

caca/event.c

@@ -42,9 +42,9 @@ static int _lowlevel_event(caca_display_t *, caca_event_t *);
 
 /** \brief Get the next mouse or keyboard input event.
  *
- *  This function polls the event queue for mouse or keyboard events matching
- *  the event mask and returns the first matching event. Non-matching events
- *  are discarded. If \c event_mask is zero, the function returns immediately.
+ *  Poll the event queue for mouse or keyboard events matching the event
+ *  mask and return the first matching event. Non-matching events are
+ *  discarded. If \c event_mask is zero, the function returns immediately.
  *
  *  The timeout value tells how long this function needs to wait for an
  *  event. A value of zero returns immediately and the function returns zero
@@ -114,7 +114,7 @@ int caca_get_event(caca_display_t *dp, unsigned int event_mask,
 
 /** \brief Return the X mouse coordinate.
  *
- *  This function returns the X coordinate of the mouse position last time
+ *  Return the X coordinate of the mouse position last time
  *  it was detected. This function is not reliable if the ncurses or S-Lang
  *  drivers are being used, because mouse position is only detected when
  *  the mouse is clicked. Other drivers such as X11 work well.
@@ -134,7 +134,7 @@ unsigned int caca_get_mouse_x(caca_display_t *dp)
 
 /** \brief Return the Y mouse coordinate.
  *
- *  This function returns the Y coordinate of the mouse position last time
+ *  Return the Y coordinate of the mouse position last time
  *  it was detected. This function is not reliable if the ncurses or S-Lang
  *  drivers are being used, because mouse position is only detected when
  *  the mouse is clicked. Other drivers such as X11 work well.

caca/graphics.c

@@ -89,8 +89,8 @@ unsigned int caca_get_display_height(caca_display_t *dp)
 
 /** \brief Set the refresh delay.
  *
- *  This function sets the refresh delay in microseconds. The refresh delay
- *  is used by caca_refresh_display() to achieve constant framerate. See the
+ *  Set the refresh delay in microseconds. The refresh delay is used by
+ *  caca_refresh_display() to achieve constant framerate. See the
  *  caca_refresh_display() documentation for more details.
  *
  *  If the argument is zero, constant framerate is disabled. This is the
@@ -110,11 +110,11 @@ int caca_set_display_time(caca_display_t *dp, unsigned int usec)
 
 /** \brief Get the display's average rendering time.
  *
- *  This function returns the average rendering time, which is the average
- *  measured time between two caca_refresh_display() calls, in microseconds. If
- *  constant framerate was activated by calling caca_set_display_time(), the
- *  average rendering time will not be considerably shorter than the requested
- *  delay even if the real rendering time was shorter.
+ *  Get the average rendering time, which is the average measured time
+ *  between two caca_refresh_display() calls, in microseconds. If constant
+ *  framerate was activated by calling caca_set_display_time(), the average
+ *  rendering time will be close to the requested delay even if the real
+ *  rendering time was shorter.
  *
  *  This function never fails.
  *
@@ -128,9 +128,8 @@ unsigned int caca_get_display_time(caca_display_t *dp)
 
 /** \brief Flush pending changes and redraw the screen.
  *
- *  This function flushes all graphical operations and prints them to the
- *  screen. Nothing will show on the screen until caca_refresh_display() is
- *  called.
+ *  Flush all graphical operations and print them to the display device.
+ *  Nothing will show on the screen until this function is called.
  *
  *  If caca_set_display_time() was called with a non-zero value,
  *  caca_refresh_display() will use that value to achieve constant
@@ -182,8 +181,7 @@ int caca_refresh_display(caca_display_t *dp)
 
 /** \brief Show or hide the mouse pointer.
  *
- *  This function shows or hides the mouse pointer, for devices that
- *  support it.
+ *  Show or hide the mouse pointer, for devices that support such a feature.
  *
  *  If an error occurs, -1 is returned and \b errno is set accordingly:
  *  - \c ENOSYS Display driver does not support hiding the mouse pointer.

cucul/buffer.c

@@ -29,9 +29,9 @@
 
 /** \brief Load a memory area into a buffer.
  *
- *  This function creates a \e libcucul buffer that points to the given
- *  memory area. The data is not duplicated and any changes made to the
- *  original memory area appear in the buffer.
+ *  Create a \e libcucul buffer that points to the given memory area. The
+ *  data is not duplicated and any changes made to the original memory area
+ *  will appear in the buffer.
  *
  *  \param data The memory area to load.
  *  \param size The size of the memory area.
@@ -55,8 +55,8 @@ cucul_buffer_t *cucul_load_memory(void *data, unsigned long int size)
 
 /** \brief Load a file into a buffer.
  *
- *  This function loads a file into memory and returns a \e libcucul buffer
- *  for use with other functions.
+ *  Load a file into memory and returns a \e libcucul buffer for use with
+ *  other functions.
  *
  *  \param file The filename
  *  \return A \e libcucul buffer containing the file's contents, or NULL
@@ -102,8 +102,8 @@ cucul_buffer_t *cucul_load_file(char const *file)
 #endif
 /** \brief Get the buffer size.
  *
- *  This function returns the length (in bytes) of the memory area stored
- *  in the given \e libcucul buffer.
+ *  Return the length (in bytes) of the memory area stored in the given
+ *  \e libcucul buffer.
  *
  *  This function never fails.
  *
@@ -117,7 +117,7 @@ unsigned long int cucul_get_buffer_size(cucul_buffer_t *buf)
 
 /** \brief Get the buffer data.
  *
- *  This function returns a pointer to the memory area stored in the given
+ *  Get a pointer to the memory area stored in the given
  *  \e libcucul buffer.
  *
  *  This function never fails.
@@ -132,8 +132,7 @@ void * cucul_get_buffer_data(cucul_buffer_t *buf)
 
 /** \brief Free a buffer.
  *
- *  This function frees the structures associated with the given
- *  \e libcucul buffer.
+ *  Free the structures associated with the given \e libcucul buffer.
  *
  *  This function never fails.
  *

cucul/canvas.c

@@ -43,12 +43,12 @@
 
 /** \brief Print an ASCII or Unicode character.
  *
- *  This function prints an ASCII or Unicode character at the given
- *  coordinates, using the default foreground and background values.
+ *  Print an ASCII or Unicode character at the given coordinates, using
+ *  the default foreground and background colour values.
  *
  *  If the coordinates are outside the canvas boundaries, nothing is printed.
- *  If a fullwidth Unicode character gets overwritten, its remaining parts
- *  are replaced with spaces. If the canvas' boundaries would split the
+ *  If a fullwidth Unicode character gets overwritten, its remaining visible
+ *  parts are replaced with spaces. If the canvas' boundaries would split the
  *  fullwidth character in two, a space is printed instead.
  *
  *  The behaviour when printing non-printable characters or invalid UTF-32
@@ -125,8 +125,8 @@ int cucul_putchar(cucul_canvas_t *cv, int x, int y, unsigned long int ch)
 
 /** \brief Get the Unicode character at the given coordinates.
  *
- *  This function gets the ASCII or Unicode value of the character at
- *  the given coordinates. If the value is less or equal to 127 (0x7f),
+ *  Get the ASCII or Unicode value of the character at the given
+ *  coordinates. If the value is less or equal to 127 (0x7f),
  *  the character can be printed as ASCII. Otherise, it must be handled
  *  as a UTF-32 value.
  *
@@ -144,7 +144,7 @@ int cucul_putchar(cucul_canvas_t *cv, int x, int y, unsigned long int ch)
  *  \param x X coordinate.
  *  \param y Y coordinate.
  *  \param ch The requested character value.
- *  \return The character always returns 0.
+ *  \return This function always returns 0.
  */
 unsigned long int cucul_getchar(cucul_canvas_t *cv, int x, int y)
 {
@@ -156,9 +156,9 @@ unsigned long int cucul_getchar(cucul_canvas_t *cv, int x, int y)
 
 /** \brief Print a string.
  *
- *  This function prints an UTF-8 string at the given coordinates, using the
- *  default foreground and background values. The coordinates may be outside
- *  the canvas boundaries (eg. a negative Y coordinate) and the string will
+ *  Print an UTF-8 string at the given coordinates, using the default
+ *  foreground and background values. The coordinates may be outside the
+ *  canvas boundaries (eg. a negative Y coordinate) and the string will
  *  be cropped accordingly if it is too long.
  *
  *  See cucul_putchar() for more information on how fullwidth characters
@@ -198,11 +198,11 @@ int cucul_putstr(cucul_canvas_t *cv, int x, int y, char const *s)
 
 /** \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 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.
+ *  Format a string at the given coordinates, using the default foreground
+ *  and background values. The coordinates may be outside 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.
  *
  *  This function never fails.
  *
@@ -244,7 +244,7 @@ int cucul_printf(cucul_canvas_t *cv, int x, int y, char const *format, ...)
 
 /** \brief Clear the canvas.
  *
- *  This function clears the canvas using the current background colour.
+ *  Clear the canvas using the current foreground and background colours.
  *
  *  This function never fails.
  *
@@ -267,7 +267,7 @@ int cucul_clear_canvas(cucul_canvas_t *cv)
 
 /** \brief Blit a canvas onto another one.
  *
- *  This function blits a canvas onto another one at the given coordinates.
+ *  Blit a canvas onto another one at the given coordinates.
  *  An optional mask canvas can be used.
  *
  *  If an error occurs, -1 is returned and \b errno is set accordingly:
@@ -348,7 +348,7 @@ int cucul_blit(cucul_canvas_t *dst, int x, int y,
 
 /** \brief Set a canvas' new boundaries.
  *
- *  This function sets new boundaries for a canvas. It can be used to crop a
+ *  Set new boundaries for a canvas. This function can be used to crop a
  *  canvas, to expand it or for combinations of both actions.
  *
  *  If an error occurs, -1 is returned and \b errno is set accordingly:

cucul/charset.c

@@ -94,9 +94,9 @@ static uint32_t const cp437_lookup2[] =
 
 /** \brief Convert a UTF-8 character to UTF-32.
  *
- *  This function converts a UTF-8 character read from a string and returns
- *  its value in the UTF-32 character set. If the second argument is not null,
- *  the total number of read bytes is written in it.
+ *  Convert a UTF-8 character read from a string and return its value in
+ *  the UTF-32 character set. If the second argument is not null, the total
+ *  number of read bytes is written in it.
  *
  *  If a null byte was reached before the expected end of the UTF-8 sequence,
  *  this function returns zero and the number of read bytes is set to zero.
@@ -138,8 +138,8 @@ unsigned long int cucul_utf8_to_utf32(char const *s, unsigned int *read)
 
 /** \brief Convert a UTF-32 character to UTF-8.
  *
- *  This function converts a UTF-32 character read from a string and writes
- *  its value in the UTF-8 character set into the given buffer.
+ *  Convert a UTF-32 character read from a string and write its value in
+ *  the UTF-8 character set into the given buffer.
  *
  *  This function never fails, but its behaviour with illegal UTF-32 characters
  *  is undefined.
@@ -181,9 +181,8 @@ unsigned int cucul_utf32_to_utf8(char *buf, unsigned long int ch)
 
 /** \brief Convert a UTF-32 character to CP437.
  *
- *  This function converts a UTF-32 character read from a string and returns
- *  its value in the CP437 character set, or "?" if the character has no
- *  equivalent.
+ *  Convert a UTF-32 character read from a string and return its value in
+ *  the CP437 character set, or "?" if the character has no equivalent.
  *
  *  This function never fails.
  *
@@ -213,9 +212,9 @@ unsigned char cucul_utf32_to_cp437(unsigned long int ch)
 
 /** \brief Convert a CP437 character to UTF-32.
  *
- *  This function converts a CP437 character read from a string and returns
- *  its value in the UTF-32 character set, or zero if the character is a
- *  CP437 control character.
+ *  Convert a CP437 character read from a string and return its value in
+ *  the UTF-32 character set, or zero if the character is a CP437 control
+ *  character.
  *
  *  This function never fails.
  *
@@ -238,9 +237,10 @@ unsigned long int cucul_cp437_to_utf32(unsigned char ch)
 
 /** \brief Tell whether a UTF-32 character is fullwidth.
  *
- *  This function returns 1 if the given UTF-32 character should be
- *  printed at twice the normal width (fullwidth), or 0 if it is a
- *  standard-width character or if the library does not know.
+ *  Check whether the given UTF-32 character should be printed at twice
+ *  the normal width (fullwidth characters). If the character is unknown
+ *  or if its status cannot be decided, it is treated as a standard-width
+ *  character.
  *
  *  This function never fails.
  *

cucul/colour.c

@@ -37,7 +37,7 @@ static const uint16_t ansitab[16] =
 
 /** \brief Set the default colour pair.
  *
- *  This function sets the default ANSI colour pair. String functions such as
+ *  Set the default ANSI colour pair for drawing. String functions such as
  *  caca_printf() and graphical primitive functions such as caca_draw_line()
  *  will use these colours.
  *
@@ -70,7 +70,7 @@ int cucul_set_color(cucul_canvas_t *cv, unsigned char fg, unsigned char bg)
 
 /** \brief Set the default colour pair (truecolor version).
  *
- *  This function sets the default colour pair. String functions such as
+ *  Set the default colour pair for drawing. String functions such as
  *  caca_printf() and graphical primitive functions such as caca_draw_line()
  *  will use these colours.
  *
@@ -110,10 +110,10 @@ int cucul_set_truecolor(cucul_canvas_t *cv, unsigned int fg, unsigned int bg)
 
 /** \brief Get the colour pair at the given coordinates.
  *
- *  This function gets the internal \e libcucul colour pair value of the
- *  character at the given coordinates. The colour pair value has 32
- *  significant bits: the lower 16 are for the foreground colour, the higher
- *  16 are for the background.
+ *  Get the internal \e libcucul colour pair value of the character at the
+ *  given coordinates. The colour pair value has 32 significant bits: the
+ *  lower 16 bits are for the foreground colour, the higher 16 bits are for
+ *  the background.
  *
  *  If the coordinates are outside the canvas boundaries, the current colour
  *  pair is returned.

cucul/cucul.c

@@ -38,9 +38,9 @@
 
 /** \brief Initialise a \e libcucul canvas.
  *
- *  This function initialises internal \e libcucul structures and the backend
- *  that will be used for subsequent graphical operations. It must be the
- *  first \e libcucul function to be called in a function. cucul_free_canvas()
+ *  Initialise internal \e libcucul structures and the backend that will
+ *  be used for subsequent graphical operations. It must be the first
+ *  \e libcucul function to be called in a function. cucul_free_canvas()
  *  should be called at the end of the program to free all allocated resources.
  *
  *  If one of the desired canvas coordinates is zero, a default canvas size
@@ -124,7 +124,7 @@ nomem:
 
 /** \brief Resize a canvas.
  *
- *  This function sets the canvas width and height, in character cells.
+ *  Set the canvas' width and height, in character cells.
  *
  *  The contents of the canvas are preserved to the extent of the new
  *  canvas size. Newly allocated character cells at the right and/or at
@@ -163,7 +163,7 @@ int cucul_set_canvas_size(cucul_canvas_t *cv, unsigned int width,
 
 /** \brief Get the canvas width.
  *
- *  This function returns the current canvas width, in character cells.
+ *  Return the current canvas' width, in character cells.
  *
  *  This function never fails.
  *
@@ -177,7 +177,7 @@ unsigned int cucul_get_canvas_width(cucul_canvas_t *cv)
 
 /** \brief Get the canvas height.
  *
- *  This function returns the current canvas height, in character cells.
+ *  Returns the current canvas' height, in character cells.
  *
  *  This function never fails.
  *
@@ -191,8 +191,8 @@ unsigned int cucul_get_canvas_height(cucul_canvas_t *cv)
 
 /** \brief Translate a colour index into the colour's name.
  *
- *  This function translates a cucul_color enum into a human-readable
- *  description string of the associated colour.
+ *  Translate a cucul_color enum into a human-readable string describing
+ *  the corresponding colour.
  *
  *  This function never fails.
  *
@@ -230,8 +230,8 @@ char const *cucul_get_color_name(unsigned int color)
 
 /** \brief Uninitialise \e libcucul.
  *
- *  This function frees all resources allocated by cucul_create_canvas(). After
- *  cucul_free_canvas() has been called, no other \e libcucul functions may be
+ *  Free all resources allocated by cucul_create_canvas(). After
+ *  this function has been called, no other \e libcucul functions may be
  *  used unless a new call to cucul_create_canvas() is done.
  *
  *  If an error occurs, -1 is returned and \b errno is set accordingly:
@@ -269,6 +269,8 @@ int cucul_free_canvas(cucul_canvas_t *cv)
 }
 
 /** \brief Generate a random integer within a range.
+ *
+ *  Generate a random integer within the given range.
  *
  *  This function never fails.
  *

cucul/import.c

@@ -47,14 +47,14 @@ static void ansi_parse_grcm(cucul_canvas_t *, struct ansi_grcm *,
 
 /** \brief Import a buffer into a canvas
  *
- *  This function imports a libcucul buffer as returned by cucul_load_memory()
+ *  Import a libcucul buffer as returned by cucul_load_memory()
  *  or cucul_load_file() into an internal libcucul canvas.
  *
  *  Valid values for \c format are:
  *  - \c "": attempt to autodetect the file format.
  *  - \c "text": import ASCII text files.
  *  - \c "ansi": import ANSI files.
- *  - \c "utf8": import UTF-8 files with ANSI colour files.
+ *  - \c "utf8": import UTF-8 files with ANSI colour codes.
  *  - \c "caca": import native libcaca files.
  *
  *  If an error occurs, NULL is returned and \b errno is set accordingly:

cucul/sprite.c

@@ -32,7 +32,7 @@
 
 /** \brief Get the number of frames in a canvas.
  *
- *  This function returns the current canvas frame count.
+ *  Return the current canvas' frame count.
  *
  *  This function never fails.
  *
@@ -46,9 +46,9 @@ unsigned int cucul_get_canvas_frame_count(cucul_canvas_t *cv)
 
 /** \brief Activate a given canvas frame.
  *
- *  This function sets the active canvas frame. All subsequent drawing
- *  operations will be performed on that frame. The current painting
- *  context set by cucul_set_color() or cucul_set_truecolor() is inherited.
+ *  Set the active canvas frame. All subsequent drawing operations will
+ *  be performed on that frame. The current painting context set by
+ *  cucul_set_color() or cucul_set_truecolor() is inherited.
  *
  *  If the frame index is outside the canvas' frame range, nothing happens.
  *
@@ -79,8 +79,8 @@ int cucul_set_canvas_frame(cucul_canvas_t *cv, unsigned int frame)
 
 /** \brief Add a frame to a canvas.
  *
- *  This function creates a new frame within the given canvas. Its contents
- *  are copied from the currently active frame.
+ *  Create a new frame within the given canvas. Its contents are copied
+ *  from the currently active frame.
  *
  *  The frame index indicates where the frame should be inserted. Valid
  *  values range from 0 to the current canvas frame count. If the frame
@@ -131,10 +131,7 @@ int cucul_create_canvas_frame(cucul_canvas_t *cv, unsigned int frame)
 
 /** \brief Remove a frame from a canvas.
  *
- *  This function deletes a frame from a given canvas.
- *
- *  It is not legal to remove the last frame from a canvas. Such a request
- *  will be ignored by cucul_free_canvas_frame().
+ *  Delete a frame from a given canvas.
  *
  *  The frame index indicates the frame to delete. Valid values range from
  *  0 to the current canvas frame count minus 1. If the frame index is

cucul/transform.c

@@ -30,8 +30,8 @@ static uint32_t rotatechar(uint32_t ch);
 
 /** \brief Invert a canvas' colours.
  *
- *  This function inverts a canvas' colours (black becomes white, red
- *  becomes cyan, etc.) without changing the characters in it.
+ *  Invert a canvas' colours (black becomes white, red becomes cyan, etc.)
+ *  without changing the characters in it.
  *
  *  This function never fails.
  *
@@ -54,8 +54,8 @@ int cucul_invert(cucul_canvas_t *cv)
 
 /** \brief Flip a canvas horizontally.
  *
- *  This function flips a canvas horizontally, choosing characters that
- *  look like the mirrored version wherever possible.
+ *  Flip a canvas horizontally, choosing characters that look like the
+ *  mirrored version wherever possible.
  *
  *  This function never fails.
  *
@@ -111,8 +111,8 @@ int cucul_flip(cucul_canvas_t *cv)
 
 /** \brief Flip a canvas vertically.
  *
- *  This function flips a canvas vertically, choosing characters that
- *  look like the mirrored version wherever possible.
+ *  Flip a canvas vertically, choosing characters that look like the
+ *  mirrored version wherever possible.
  *
  *  This function never fails.
  *
@@ -154,9 +154,8 @@ int cucul_flop(cucul_canvas_t *cv)
 
 /** \brief Rotate a canvas.
  *
- *  This function applies a 180 degrees transformation to a canvas,
- *  choosing characters that look like the mirrored version wherever
- *  possible.
+ *  Apply a 180-degree transformation to a canvas, choosing characters
+ *  that look like the upside-down version wherever possible.
  *
  *  This function never fails.
  *