Re: [AD] Documentation update

["Eric Botcazou" <ebotcazou@xxxxxxxxxx>]

> > ... pointed to ... (but I'm not sure so if a native English speaker is
> > around there...)
>
> To me all sound right. Googling I found a more pedantic version
> "pointed at by", among many other versions with to or by.

grep shows that "pointed to" is more prevalent in allegro._tx so I think we
should standardize on it.

> > This time I'm 100% sure: the second ASSERT is superfluous. And
> > the first one is probably overbroad, because n=0 should work.
>
> Wait, I didn't use the correct variable name. Those asserts should
> have checked size.

Obviously. The diff against unicode.c looks now fine.


A few remaining nits in the docs:

- it's "graphics mode", not "graphic mode"

 @@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
+   "character value c" can be encoded correctly in the current format,
which
+   can be useful if you are converting from Unicode to ASCII or another
+   encoding format where the range of valid characters is limited.

Superfluous quotes (sorry for the confusion).


 @@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 if 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 (without s, the loop most likely stops at the
first null character). Same for other functions.


 @@char *@ustrcat(char *dest, const char *src);
 @xref uconvert, ustrzcat, ustrncat
 @eref exunicod
-   This function concatenates src to the end of dest. The return value is
the
-   value of dest.
+   This function concatenates src to the end of dest. You should try to
avoid
+   this function because it is very easy to overflow the destination
buffer,
+   use ustrzcat instead.

...buffer. Use ustrzcat...


 @@char *@ustrncat(char *dest, const char *src, int n);
 @xref uconvert, ustrcat, ustrzncat
    This function is like ustrcat() except that no more than n characters
-   from src are appended to the end of dest. If the terminating NULL
+   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. If n
-   characters are written before a terminating NULL is encountered, the
-   function appends its own NULL character to dest, so that n+1 characters
-   are written. The return value is the value of dest.
+   null character is copied, but no other characters are written. If n
+   characters are written before a terminating null is encountered, the
+   function appends its own null character to dest, so that n+1 characters
+   are written. You should try to avoid this function because it is very
+   easy to overflow the destination buffer, use ustrzcat instead.

...buffer. Use ustrz_n_cat instead


--
Eric Botcazou