Re: [AD] Documentation update

["Eric Botcazou" <ebotcazou@xxxxxxxxxx>]

> Another chunk.

Some nits:

@@ -259,8 +259,12 @@
    Finds out the currently selected desktop color depth. You can use this
    information to make your program use the same color depth as the
desktop,
    which will likely make it run faster because the graphic driver won't be
-   doing unnecessary color conversions behind your back. Usually you want
to
-   call this before setting the graphic mode. Example:
+   doing unnecessary color conversions behind your back.
+
+   Under certain OSes, switching to a full screen graphic mode implicitly
+   changes the desktop's resolution too. Thus, you have to call this
function
+   before setting any graphic mode in order to retrieve the desktop's real
+   color depth. Example:
 <codeblock>
       allegro_init();
       ...

Under some OSes...graphics mode may automatically (better than implicitly)
change the desktop color depth.You have, therefore, to... graphics ... the
real desktop color depth.


@@ -277,8 +281,12 @@
    information to avoid creating windows bigger than the current
resolution.
    This is especially important for some windowed drivers which are unable
    to create windows bigger than the desktop. Each parameter is a pointer
-   to an integer where one dimension of the screen will be stored. Usually
-   you want to call this before setting the graphic mode. Example:
+   to an integer where one dimension of the screen will be stored.
+
+   Under certain OSes, switching to a full screen graphic mode implicitly
+   changes the desktop's resolution too. Thus, you have to call this
function
+   before setting any graphic mode in order to retrieve the desktop's real
+   resolution. Example:
 <codeblock>
       int width, height;

Under some OSes...graphics mode may automatically (better than implicitly)
change the desktop resolution.You have, therefore, to... graphics ... the
real desktop resolution.


+   Low level helper function for reading Unicode text data.
+@retval
+   Returns the character pointed by s in the current encoding format.

... pointed to ... (but I'm not sure so if a native English speaker is
around there...)


 @@int @ugetx(char **s);
 @@int @ugetxc(const char **s);
 @xref ugetc, usetc, uwidth, ucwidth, uisok
-   Low level helper function for reading Unicode text data. Given the
-   address of a pointer to a string in the current encoding format, it
-   returns the next character from the string, and advances the pointer to
-   the character after the one just read.
-
-   ugetxc is provided for working with pointer-to-pointer-to-const char
-   data.
+   Low level helper function for reading Unicode text data similar to
+   ugetc. ugetxc is provided for working with pointer-to-pointer-to-const
+   char data.

This is confusing: ugetx (and ugetxc) are *not* similar to ugetc, because
the former two advance the pointer and the latter doesn't.


+@retval
+   Returns the character pointed by s in the current encoding format, and
+   advances the pointer to the next character after the one just returned.

... pointed to ... (with the same reserve as above)...


-   Low level helper function for writing Unicode text data. It writes the
-   specified character to the given address in the current encoding format,
-   and returns the number of bytes written.
+   Low level helper function for writing Unicode text data. Writes the
+   character c to the given string position pointed by s.

"address" was better than "position", because the former is traditionally a
pointer while the latter is an int. Maybe "to the address specified by s".

+@retval
+   Returns the number of bytes writen to the string, which is the width of
the
+   character in the current encoding format.

write, writing, written

Returns the number of bytes written (which is equal to...).


 @@int @uisok(int c);
 @xref ugetc, ugetx, usetc, uwidth, ucwidth
-   Low level helper function for testing Unicode text data. Tests whether
-   the specified value can be correctly encoded in the current format.
+   Low level helper function for testing Unicode text data. Finds out if
the
+   Unicode character "c" can be encoded correctly in the current format,
which
+   can be useful if you are converting Unicode to ASCII or another encoding
+   format where the range of valid characters is limited.

..."character value c"... converting from Unicode to ASCII...


 @@int @uoffset(const char *s, int index);
 @xref ugetat, usetat, uinsert, uremove
-   Returns the offset in bytes from the start of the string to the
character
-   at the specified index. If the index is negative, it counts backward
from
-   the end of the string, so an index of -1 will return an offset to the
last
-   character.
+   Finds out how many bytes there are from the start of the string to the
+   character at the specified index. If the index is negative, it counts
+   backward from the end of the string, so an index of -1 will return an
+   offset to the last character.

This is confusing: do you count the character in the "how many bytes"?
"Finds out the offset (in bytes from the start of string) of the character
at the specified index in the string s."


-   Returns the character value at the specified index within the string. A
-   zero index parameter will return the first character of the string. If
-   the index is negative, it counts backward from the end of the string, so
-   an index of -1 will return the last character of the string.
+   Finds out what character value is at the specified index within the
+   string. A zero index parameter will return the first character of the
+   string. If the index is negative, it counts backward from the end of the
+   string, so an index of -1 will return the last character of the string.
+@retval

Finds out the character value at the specified index in the string.

+   Returns the character value at the specified index within the string.

... in the string.


-   Replaces the character at the specified index within the string with
-   value c, handling any adjustments for variable width data (ie. if c
-   encodes to a different width than the previous value at that location).
+   Replaces the character at the specified index within the string with
+   value c, handling any adjustments for variable width data (ie. if c
encodes
+   to a different width than the previous value at that location). If the
+   index is negative, it counts backward from the end of the string.

... in the string...

+@retval
    Returns the number of bytes by which the trailing part of the string was
-   moved. If the index is negative, it counts backward from the end of the
-   string.
+   moved. This will interest you only with text encoding formats where
+   characters hava a variable length, like UTF-8.

This is of interest only with... have...


 @@int @uinsert(char *s, int index, int c);
 @xref uoffset, ugetat, usetat, uremove
    Inserts the character c at the specified index within the string,
sliding
-   the rest of the data along to make room. Returns the number of bytes by
-   which the trailing part of the string was moved. If the index is
-   negative, it counts backward from the end of the string.
+   the rest of the data along to make room. If the index is negative, it
+   counts backward from the end of the string.

..in the string, sliding...


 @@int @uremove(char *s, int index);
 @xref uoffset, ugetat, usetat, uinsert
    Removes the character at the specified index within the string, sliding
-   the rest of the data back to fill the gap. Returns the number of bytes
by
-   which the trailing part of the string was moved. If the index is
-   negative, it counts backward from the end of the string.
+   the rest of the data back to fill the gap. If the index is negative, it
+   counts backward from the end of the string.

...in the string, sliding


@@ -1029,9 +1054,10 @@
 @xref _ustrdup, uconvert, ustrsize, ustrsizez
 @eref exconfig
    This functions copies the NULL-terminated string src into a newly
-   allocated area of memory. The memory returned by this call must be freed
-   by the caller. Returns NULL if it cannot allocate space for the
duplicated
-   string.
+   allocated area of memory, effectively duplicating it.

null-terminated string

+@retval
+   Returns the newly allocated string. This memory has to be freed by the
+   caller. Returns NULL if it cannot allocate space for the duplicated
string.

"must" was fine I think.


 @@char *@ustrcpy(char *dest, const char *src);
 @xref uconvert, ustrzcpy, ustrncpy
 @eref exunicod
-   This function copies src (including the terminating NULL character) into
-   dest. The return value is the value of dest.
+   This function copies src (including the terminating NULL character(s))
+   into dest. You should try to avoid this function because it is very easy
+   to overflow the destination buffer, use ustrzcpy instead.

terminating null character... destination buffer. Use...


 @@char *@ustrzcpy(char *dest, int size, const char *src);
 @xref uconvert, ustrcpy, ustrzncpy
 @eref exgui
-   This function copies src (including the terminating NULL character) into
+   This function copies src (including the terminating NULL character(s))
into
    dest, whose length in bytes is specified by size and which is guaranteed
-   to be NULL-terminated. The return value is the value of dest.
+   to be NULL-terminated even when src is bigger than size.
+
+   Note that, even for empty strings, your destination string must have at
+   least enough bytes to store the terminating null character of the
string,
+   and your parameter size must reflect this. Otherwise, the debug version
of
+   Allegro will abort at an assertion, and the release version of Allegro
+   will overrun the destination buffer.

terminating  null character... null-terminated even if...


 @@char *@ustrzcat(char *dest, int size, const char *src);
 @xref uconvert, ustrcat, ustrzncat
 @eref exgui
    This function concatenates src to the end of dest, whose length in bytes
-   is specified by size and which is guaranteed to be NULL-terminated. The
-   return value is the value of dest.
+   is specified by size and which is guaranteed to be NULL-terminated even
+   when src is bigger than size.
+
+   Note that, even for empty strings, your destination string must have at
+   least enough bytes to store the terminating null character of the
string,
+   and your parameter size must reflect this. Otherwise, the debug version
of
+   Allegro will abort at an assertion, and the release version of Allegro
+   will overrun the destination buffer.

...null-terminated...


 @@char *@ustrncpy(char *dest, const char *src, int n);
 @xref uconvert, ustrcpy, ustrzncpy
    This function is like ustrcpy() except that no more than n characters
    from src are copied into dest. If src is shorter than n characters, NULL
    characters are appended to dest as padding until n characters have been
-   written. Note that if src is longer than n characters, dest will not be
-   NULL-terminated. The return value is the value of dest.
+   written.
+
+   Note that if src is longer than n characters, dest will not be
+   NULL-terminated.

null characters... null-terminated


 @@char *@ustrzncpy(char *dest, int size, const char *src, int n);
 @xref uconvert, ustrzcpy, ustrncpy
    This function is like ustrzcpy() except that no more than n characters
    from src are copied into dest. If src is shorter than n characters, NULL
    characters are appended to dest as padding until n characters have been
-   written. Note that dest is guaranteed to be NULL-terminated. The return
-   value is the value of dest.
+   written. In any case, dest is guaranteed to be NULL-terminated.
+
+   Note that, even for empty strings, your destination string must have at
+   least enough bytes to store the terminating null character of the
string,
+   and your parameter size must reflect this. Otherwise, the debug version
of
+   Allegro will abort at an assertion, and the release version of Allegro
+   will overrun the destination buffer.

null characters... null-terminated


@@ -1107,33 +1170,45 @@
    from src are appended to the end of dest. If the terminating NULL
    character in src is reached before n characters have been written, the
    NULL character is copied, but no other characters are written. Note that
-   dest is guaranteed to be NULL-terminated. The return value is the value
-   of dest.
+   dest is guaranteed to be NULL-terminated.

null character... null-terminated


@@ -1898,13 +1900,14 @@
    ASSERT(dest);
    ASSERT(src);
    ASSERT(size >= 0);
-   ASSERT(n >= 0);
+   ASSERT(n > 0);

    /* detect raw ustrncpy() call */
    if (size == INT_MAX)
       ansi_oddness = TRUE;

    size -= ucwidth(0);
+   ASSERT(n >= 0);

    /* copy at most n characters */
    while (((c = ugetxc(&src)) != 0) && (len < n)) {


This time I'm 100% sure: the second ASSERT is superfluous. And the first one
is probably overbroad, because n=0 should work.

--
Eric Botcazou