Changeset 1231 for libcaca/trunk


Ignore:
Timestamp:
Oct 26, 2006, 12:06:21 AM (16 years ago)
Author:
Sam Hocevar
Message:
  • Removed "This function..." constructs from documentation. Fixed a few documentation errors or imprecisions.
Location:
libcaca/trunk
Files:
10 edited

Legend:

Unmodified
Added
Removed

  • libcaca/trunk/caca/event.c

    r1006 r1231  
    4343/** \brief Get the next mouse or keyboard input event.
    4444 *
    45  *  This function polls the event queue for mouse or keyboard events matching
    46  *  the event mask and returns the first matching event. Non-matching events
    47  *  are discarded. If \c event_mask is zero, the function returns immediately.
     45 *  Poll the event queue for mouse or keyboard events matching the event
     46 *  mask and return the first matching event. Non-matching events are
     47 *  discarded. If \c event_mask is zero, the function returns immediately.
    4848 *
    4949 *  The timeout value tells how long this function needs to wait for an
    … …  
    115115/** \brief Return the X mouse coordinate.
    116116 *
    117  *  This function returns the X coordinate of the mouse position last time
     117 *  Return the X coordinate of the mouse position last time
    118118 *  it was detected. This function is not reliable if the ncurses or S-Lang
    119119 *  drivers are being used, because mouse position is only detected when
    … …  
    135135/** \brief Return the Y mouse coordinate.
    136136 *
    137  *  This function returns the Y coordinate of the mouse position last time
     137 *  Return the Y coordinate of the mouse position last time
    138138 *  it was detected. This function is not reliable if the ncurses or S-Lang
    139139 *  drivers are being used, because mouse position is only detected when

  • libcaca/trunk/caca/graphics.c

    r1006 r1231  
    9090/** \brief Set the refresh delay.
    9191 *
    92  *  This function sets the refresh delay in microseconds. The refresh delay
    93  *  is used by caca_refresh_display() to achieve constant framerate. See the
     92 *  Set the refresh delay in microseconds. The refresh delay is used by
     93 *  caca_refresh_display() to achieve constant framerate. See the
    9494 *  caca_refresh_display() documentation for more details.
    9595 *
    … …  
    111111/** \brief Get the display's average rendering time.
    112112 *
    113  *  This function returns the average rendering time, which is the average
    114  *  measured time between two caca_refresh_display() calls, in microseconds. If
    115  *  constant framerate was activated by calling caca_set_display_time(), the
    116  *  average rendering time will not be considerably shorter than the requested
    117  *  delay even if the real rendering time was shorter.
     113 *  Get the average rendering time, which is the average measured time
     114 *  between two caca_refresh_display() calls, in microseconds. If constant
     115 *  framerate was activated by calling caca_set_display_time(), the average
     116 *  rendering time will be close to the requested delay even if the real
     117 *  rendering time was shorter.
    118118 *
    119119 *  This function never fails.
    … …  
    129129/** \brief Flush pending changes and redraw the screen.
    130130 *
    131  *  This function flushes all graphical operations and prints them to the
    132  *  screen. Nothing will show on the screen until caca_refresh_display() is
    133  *  called.
     131 *  Flush all graphical operations and print them to the display device.
     132 *  Nothing will show on the screen until this function is called.
    134133 *
    135134 *  If caca_set_display_time() was called with a non-zero value,
    … …  
    183182/** \brief Show or hide the mouse pointer.
    184183 *
    185  *  This function shows or hides the mouse pointer, for devices that
    186  *  support it.
     184 *  Show or hide the mouse pointer, for devices that support such a feature.
    187185 *
    188186 *  If an error occurs, -1 is returned and \b errno is set accordingly:

  • libcaca/trunk/cucul/buffer.c

    r1048 r1231  
    3030/** \brief Load a memory area into a buffer.
    3131 *
    32  *  This function creates a \e libcucul buffer that points to the given
    33  *  memory area. The data is not duplicated and any changes made to the
    34  *  original memory area appear in the buffer.
     32 *  Create a \e libcucul buffer that points to the given memory area. The
     33 *  data is not duplicated and any changes made to the original memory area
     34 *  will appear in the buffer.
    3535 *
    3636 *  \param data The memory area to load.
    … …  
    5656/** \brief Load a file into a buffer.
    5757 *
    58  *  This function loads a file into memory and returns a \e libcucul buffer
    59  *  for use with other functions.
     58 *  Load a file into memory and returns a \e libcucul buffer for use with
     59 *  other functions.
    6060 *
    6161 *  \param file The filename
    … …  
    103103/** \brief Get the buffer size.
    104104 *
    105  *  This function returns the length (in bytes) of the memory area stored
    106  *  in the given \e libcucul buffer.
     105 *  Return the length (in bytes) of the memory area stored in the given
     106 *  \e libcucul buffer.
    107107 *
    108108 *  This function never fails.
    … …  
    118118/** \brief Get the buffer data.
    119119 *
    120  *  This function returns a pointer to the memory area stored in the given
     120 *  Get a pointer to the memory area stored in the given
    121121 *  \e libcucul buffer.
    122122 *
    … …  
    133133/** \brief Free a buffer.
    134134 *
    135  *  This function frees the structures associated with the given
    136  *  \e libcucul buffer.
     135 *  Free the structures associated with the given \e libcucul buffer.
    137136 *
    138137 *  This function never fails.

  • libcaca/trunk/cucul/canvas.c

    r1224 r1231  
    4444/** \brief Print an ASCII or Unicode character.
    4545 *
    46  *  This function prints an ASCII or Unicode character at the given
    47  *  coordinates, using the default foreground and background values.
     46 *  Print an ASCII or Unicode character at the given coordinates, using
     47 *  the default foreground and background colour values.
    4848 *
    4949 *  If the coordinates are outside the canvas boundaries, nothing is printed.
    50  *  If a fullwidth Unicode character gets overwritten, its remaining parts
    51  *  are replaced with spaces. If the canvas' boundaries would split the
     50 *  If a fullwidth Unicode character gets overwritten, its remaining visible
     51 *  parts are replaced with spaces. If the canvas' boundaries would split the
    5252 *  fullwidth character in two, a space is printed instead.
    5353 *
    … …  
    126126/** \brief Get the Unicode character at the given coordinates.
    127127 *
    128  *  This function gets the ASCII or Unicode value of the character at
    129  *  the given coordinates. If the value is less or equal to 127 (0x7f),
     128 *  Get the ASCII or Unicode value of the character at the given
     129 *  coordinates. If the value is less or equal to 127 (0x7f),
    130130 *  the character can be printed as ASCII. Otherise, it must be handled
    131131 *  as a UTF-32 value.
    … …  
    145145 *  \param y Y coordinate.
    146146 *  \param ch The requested character value.
    147  *  \return The character always returns 0.
     147 *  \return This function always returns 0.
    148148 */
    149149unsigned long int cucul_getchar(cucul_canvas_t *cv, int x, int y)
    … …  
    157157/** \brief Print a string.
    158158 *
    159  *  This function prints an UTF-8 string at the given coordinates, using the
    160  *  default foreground and background values. The coordinates may be outside
    161  *  the canvas boundaries (eg. a negative Y coordinate) and the string will
     159 *  Print an UTF-8 string at the given coordinates, using the default
     160 *  foreground and background values. The coordinates may be outside the
     161 *  canvas boundaries (eg. a negative Y coordinate) and the string will
    162162 *  be cropped accordingly if it is too long.
    163163 *
    … …  
    199199/** \brief Print a formated string.
    200200 *
    201  *  This function formats a string at the given coordinates, using the
    202  *  default foreground and background values. The coordinates may be outside
    203  *  the canvas boundaries (eg. a negative Y coordinate) and the string will
    204  *  be cropped accordingly if it is too long. The syntax of the format
    205  *  string is the same as for the C printf() function.
     201 *  Format a string at the given coordinates, using the default foreground
     202 *  and background values. The coordinates may be outside the canvas
     203 *  boundaries (eg. a negative Y coordinate) and the string will be cropped
     204 *  accordingly if it is too long. The syntax of the format string is the
     205 *  same as for the C printf() function.
    206206 *
    207207 *  This function never fails.
    … …  
    245245/** \brief Clear the canvas.
    246246 *
    247  *  This function clears the canvas using the current background colour.
     247 *  Clear the canvas using the current foreground and background colours.
    248248 *
    249249 *  This function never fails.
    … …  
    268268/** \brief Blit a canvas onto another one.
    269269 *
    270  *  This function blits a canvas onto another one at the given coordinates.
     270 *  Blit a canvas onto another one at the given coordinates.
    271271 *  An optional mask canvas can be used.
    272272 *
    … …  
    349349/** \brief Set a canvas' new boundaries.
    350350 *
    351  *  This function sets new boundaries for a canvas. It can be used to crop a
     351 *  Set new boundaries for a canvas. This function can be used to crop a
    352352 *  canvas, to expand it or for combinations of both actions.
    353353 *

  • libcaca/trunk/cucul/charset.c

    r1211 r1231  
    9595/** \brief Convert a UTF-8 character to UTF-32.
    9696 *
    97  *  This function converts a UTF-8 character read from a string and returns
    98  *  its value in the UTF-32 character set. If the second argument is not null,
    99  *  the total number of read bytes is written in it.
     97 *  Convert a UTF-8 character read from a string and return its value in
     98 *  the UTF-32 character set. If the second argument is not null, the total
     99 *  number of read bytes is written in it.
    100100 *
    101101 *  If a null byte was reached before the expected end of the UTF-8 sequence,
    … …  
    139139/** \brief Convert a UTF-32 character to UTF-8.
    140140 *
    141  *  This function converts a UTF-32 character read from a string and writes
    142  *  its value in the UTF-8 character set into the given buffer.
     141 *  Convert a UTF-32 character read from a string and write its value in
     142 *  the UTF-8 character set into the given buffer.
    143143 *
    144144 *  This function never fails, but its behaviour with illegal UTF-32 characters
    … …  
    182182/** \brief Convert a UTF-32 character to CP437.
    183183 *
    184  *  This function converts a UTF-32 character read from a string and returns
    185  *  its value in the CP437 character set, or "?" if the character has no
    186  *  equivalent.
     184 *  Convert a UTF-32 character read from a string and return its value in
     185 *  the CP437 character set, or "?" if the character has no equivalent.
    187186 *
    188187 *  This function never fails.
    … …  
    214213/** \brief Convert a CP437 character to UTF-32.
    215214 *
    216  *  This function converts a CP437 character read from a string and returns
    217  *  its value in the UTF-32 character set, or zero if the character is a
    218  *  CP437 control character.
     215 *  Convert a CP437 character read from a string and return its value in
     216 *  the UTF-32 character set, or zero if the character is a CP437 control
     217 *  character.
    219218 *
    220219 *  This function never fails.
    … …  
    239238/** \brief Tell whether a UTF-32 character is fullwidth.
    240239 *
    241  *  This function returns 1 if the given UTF-32 character should be
    242  *  printed at twice the normal width (fullwidth), or 0 if it is a
    243  *  standard-width character or if the library does not know.
     240 *  Check whether the given UTF-32 character should be printed at twice
     241 *  the normal width (fullwidth characters). If the character is unknown
     242 *  or if its status cannot be decided, it is treated as a standard-width
     243 *  character.
    244244 *
    245245 *  This function never fails.

  • libcaca/trunk/cucul/colour.c

    r1092 r1231  
    3838/** \brief Set the default colour pair.
    3939 *
    40  *  This function sets the default ANSI colour pair. String functions such as
     40 *  Set the default ANSI colour pair for drawing. String functions such as
    4141 *  caca_printf() and graphical primitive functions such as caca_draw_line()
    4242 *  will use these colours.
    … …  
    7171/** \brief Set the default colour pair (truecolor version).
    7272 *
    73  *  This function sets the default colour pair. String functions such as
     73 *  Set the default colour pair for drawing. String functions such as
    7474 *  caca_printf() and graphical primitive functions such as caca_draw_line()
    7575 *  will use these colours.
    … …  
    111111/** \brief Get the colour pair at the given coordinates.
    112112 *
    113  *  This function gets the internal \e libcucul colour pair value of the
    114  *  character at the given coordinates. The colour pair value has 32
    115  *  significant bits: the lower 16 are for the foreground colour, the higher
    116  *  16 are for the background.
     113 *  Get the internal \e libcucul colour pair value of the character at the
     114 *  given coordinates. The colour pair value has 32 significant bits: the
     115 *  lower 16 bits are for the foreground colour, the higher 16 bits are for
     116 *  the background.
    117117 *
    118118 *  If the coordinates are outside the canvas boundaries, the current colour

  • libcaca/trunk/cucul/cucul.c

    r1148 r1231  
    3939/** \brief Initialise a \e libcucul canvas.
    4040 *
    41  *  This function initialises internal \e libcucul structures and the backend
    42  *  that will be used for subsequent graphical operations. It must be the
    43  *  first \e libcucul function to be called in a function. cucul_free_canvas()
     41 *  Initialise internal \e libcucul structures and the backend that will
     42 *  be used for subsequent graphical operations. It must be the first
     43 *  \e libcucul function to be called in a function. cucul_free_canvas()
    4444 *  should be called at the end of the program to free all allocated resources.
    4545 *
    … …  
    125125/** \brief Resize a canvas.
    126126 *
    127  *  This function sets the canvas width and height, in character cells.
     127 *  Set the canvas' width and height, in character cells.
    128128 *
    129129 *  The contents of the canvas are preserved to the extent of the new
    … …  
    164164/** \brief Get the canvas width.
    165165 *
    166  *  This function returns the current canvas width, in character cells.
     166 *  Return the current canvas' width, in character cells.
    167167 *
    168168 *  This function never fails.
    … …  
    178178/** \brief Get the canvas height.
    179179 *
    180  *  This function returns the current canvas height, in character cells.
     180 *  Returns the current canvas' height, in character cells.
    181181 *
    182182 *  This function never fails.
    … …  
    192192/** \brief Translate a colour index into the colour's name.
    193193 *
    194  *  This function translates a cucul_color enum into a human-readable
    195  *  description string of the associated colour.
     194 *  Translate a cucul_color enum into a human-readable string describing
     195 *  the corresponding colour.
    196196 *
    197197 *  This function never fails.
    … …  
    231231/** \brief Uninitialise \e libcucul.
    232232 *
    233  *  This function frees all resources allocated by cucul_create_canvas(). After
    234  *  cucul_free_canvas() has been called, no other \e libcucul functions may be
     233 *  Free all resources allocated by cucul_create_canvas(). After
     234 *  this function has been called, no other \e libcucul functions may be
    235235 *  used unless a new call to cucul_create_canvas() is done.
    236236 *
    … …  
    270270
    271271/** \brief Generate a random integer within a range.
     272 *
     273 *  Generate a random integer within the given range.
    272274 *
    273275 *  This function never fails.

  • libcaca/trunk/cucul/import.c

    r1219 r1231  
    4848/** \brief Import a buffer into a canvas
    4949 *
    50  *  This function imports a libcucul buffer as returned by cucul_load_memory()
     50 *  Import a libcucul buffer as returned by cucul_load_memory()
    5151 *  or cucul_load_file() into an internal libcucul canvas.
    5252 *
    … …  
    5555 *  - \c "text": import ASCII text files.
    5656 *  - \c "ansi": import ANSI files.
    57  *  - \c "utf8": import UTF-8 files with ANSI colour files.
     57 *  - \c "utf8": import UTF-8 files with ANSI colour codes.
    5858 *  - \c "caca": import native libcaca files.
    5959 *

  • libcaca/trunk/cucul/sprite.c

    r920 r1231  
    3333/** \brief Get the number of frames in a canvas.
    3434 *
    35  *  This function returns the current canvas frame count.
     35 *  Return the current canvas' frame count.
    3636 *
    3737 *  This function never fails.
    … …  
    4747/** \brief Activate a given canvas frame.
    4848 *
    49  *  This function sets the active canvas frame. All subsequent drawing
    50  *  operations will be performed on that frame. The current painting
    51  *  context set by cucul_set_color() or cucul_set_truecolor() is inherited.
     49 *  Set the active canvas frame. All subsequent drawing operations will
     50 *  be performed on that frame. The current painting context set by
     51 *  cucul_set_color() or cucul_set_truecolor() is inherited.
    5252 *
    5353 *  If the frame index is outside the canvas' frame range, nothing happens.
    … …  
    8080/** \brief Add a frame to a canvas.
    8181 *
    82  *  This function creates a new frame within the given canvas. Its contents
    83  *  are copied from the currently active frame.
     82 *  Create a new frame within the given canvas. Its contents are copied
     83 *  from the currently active frame.
    8484 *
    8585 *  The frame index indicates where the frame should be inserted. Valid
    … …  
    132132/** \brief Remove a frame from a canvas.
    133133 *
    134  *  This function deletes a frame from a given canvas.
    135  *
    136  *  It is not legal to remove the last frame from a canvas. Such a request
    137  *  will be ignored by cucul_free_canvas_frame().
     134 *  Delete a frame from a given canvas.
    138135 *
    139136 *  The frame index indicates the frame to delete. Valid values range from

  • libcaca/trunk/cucul/transform.c

    r1230 r1231  
    3131/** \brief Invert a canvas' colours.
    3232 *
    33  *  This function inverts a canvas' colours (black becomes white, red
    34  *  becomes cyan, etc.) without changing the characters in it.
     33 *  Invert a canvas' colours (black becomes white, red becomes cyan, etc.)
     34 *  without changing the characters in it.
    3535 *
    3636 *  This function never fails.
    … …  
    5555/** \brief Flip a canvas horizontally.
    5656 *
    57  *  This function flips a canvas horizontally, choosing characters that
    58  *  look like the mirrored version wherever possible.
     57 *  Flip a canvas horizontally, choosing characters that look like the
     58 *  mirrored version wherever possible.
    5959 *
    6060 *  This function never fails.
    … …  
    112112/** \brief Flip a canvas vertically.
    113113 *
    114  *  This function flips a canvas vertically, choosing characters that
    115  *  look like the mirrored version wherever possible.
     114 *  Flip a canvas vertically, choosing characters that look like the
     115 *  mirrored version wherever possible.
    116116 *
    117117 *  This function never fails.
    … …  
    155155/** \brief Rotate a canvas.
    156156 *
    157  *  This function applies a 180 degrees transformation to a canvas,
    158  *  choosing characters that look like the mirrored version wherever
    159  *  possible.
     157 *  Apply a 180-degree transformation to a canvas, choosing characters
     158 *  that look like the upside-down version wherever possible.
    160159 *
    161160 *  This function never fails.
Note: See TracChangeset for help on using the changeset viewer.