Re: [AD] Documentation update

[Eric Botcazou <ebotcazou@xxxxxxxxxx>]

> Proposed update.

+comments you might think of as useful for newbies. In the case of a more
+complete example, don't forget to @xref all the allegro functions you have
+included.

Are you sure this is a good idea? Because I don't really see the benefit of

@@ -398,7 +397,7 @@
    
 @@typedef struct @BITMAP
 @xref create_bitmap, set_clip, bitmap_color_depth, RLE_SPRITE
-@domain.hid COMPILED_SPRITE, Direct access to video memory
+@xref COMPILED_SPRITE, Direct access to video memory, allegro_message
 @eref Available Allegro examples
 <codeblock>
    int w, h;               - size of the bitmap in pixels

and the others examples in the patch.


@@ -154,7 +154,6 @@
       }
       END_OF_MAIN()
 <endblock>
-
 @@extern char @allegro_id[];
    Text string containing a date and version number for the library, in case 
    you want to display these somewhere.

I'd rather see the <endblock> moved one line up, because a blank line makes 
the source ._tx file far easier to read.


@@ -899,6 +898,9 @@
    overwritten the next time this routine is called, so don't expect the 
data
    to persist across any other library calls. The static buffer has a size
    shorter than 1K, so you won't be able to convert large chunks of text.
+   Example:
+<codeblock>
+      char *p = uconvert(input_string, U_CURRENT, NULL, U_ASCII, 
0);<endblock>
 @retval
    Returns a pointer to buf (or the static buffer if you used NULL) if a
    conversion was performed. Otherwise returns a copy of s. In any cases, 
you

IMHO this is not the best example: the use of a NULL buffer is explicitly 
discouraged just above.


 @@int @ugetx(char **s);
 @@int @ugetxc(const char **s);
 @xref ugetc, usetc, uwidth, ucwidth, uisok
-   Low level helper function for reading Unicode text data. ugetxc is
-   provided for working with pointer-to-pointer-to-const char data.
+   Low level helper function for reading Unicode text data. ugetxc is 
provided
+   for working with pointer-to-pointer-to-const char data. Example:
+<codeblock>
+      char *p = string;
+      int first_letter, second_letter, third_letter;
+      first_letter = ugetx(&p);
+      second_letter = ugetx(&p);
+      third_letter = ugetx(&p);<endblock>

Why three examples for ugetx and none for ugetxc?


+   return an offset to the last character. Example:
+<codeblock>
+      char *from_third_letter = uoffset(text_string, 2);<endblock>

Wrong type.


@@ -1031,8 +1054,10 @@
 @xref uwidth, ucwidth
    Low level helper function for working with Unicode text data. Returns the 
    largest number of bytes that one character can occupy in the given 
-   encoding format. Pass U_CURRENT to represent the current format.
-
+   encoding format. Pass U_CURRENT to represent the current format. Example:
+<codeblock>
+      char *temp_buffer = malloc(256 * uwidth_max(U_UTF8));
+<endblock>
 @@int @utolower(int c);

Don't remove the blank line.


-   form feed, tab, vertical tab, or space.
-
+   form feed, tab, vertical tab, or space. Example:
+<codeblock>
+      for (counter = 0; counter &lt ustrlen(text_string); counter++) {
+	 if (uisspace(ugetat(text_string, counter)))
+	    usetat(text_string, counter, '_');
+      }
+<endblock>
 @@int @uisdigit(int c);

Likewise.


    Returns nonzero if c is a digit.
-
+<codeblock>
+      for (counter = 0; counter &lt ustrlen(text_string); counter++) {
+	 if (uisdigit(ugetat(text_string, counter)))
+	    usetat(text_string, counter, '*');
+      }
+<endblock>
 @@char *@ustrdup(const char *src)

Likewise.


-   cannot parse two strings at the same time).
+   cannot parse two strings at the same time). Example:
+<codeblock>
+      char string[50] = "some-words with dashes";

50 is superfluous.

+      char *word = ustrtok(string, " -");
+      while (word) {
+	 allegro_message("Found `%s'\n", word);
+	 word = ustrtok(NULL, " -");
+      }<endblock>

Not the best example. Just a few line above: "Warning: Since ustrtok alters
the string it is parsing, you should always copy the string to a temporary
buffer before parsing it"


+   string. Example:
+<codeblock>
+      char string[50] = "some-words with dashes";

Likewise.

+      char *last, *word = ustrtok_r(string, " -", &last);
+      while (word) {
+	 allegro_message("Found `%s'\n", word);
+	 word = ustrtok_r(NULL, " -", &last);
+      }<endblock>

Likewise.


+   normally comes from the variable `errno'. Example:
+<codeblock>
+      int file_handle = open("badname", 0, O_RDONLY);
+      if (file_handle == -1)
+	 allegro_message("%s\nSorry!\n", ustrerror(errno));<endblock>

(1) This is not ISO C.
(2) I think the example should use an Allegro function.

+@retval
+   Returns a pointer to a static string that should not be modified or
+   free'd. If you make subsequent calls to ustrerror, the string might be
+   overwritten.

Why the ' in freed? And the string will always be overwritten I think.


 @@int @usprintf(char *buf, const char *format, ...);
 @xref uconvert, uszprintf, uvsprintf
 @eref exkeys
    This function writes formatted data into the output buffer. A NULL
-   character is written to mark the end of the string. Returns the number of
-   characters written, not including the terminating NULL character.
+   character is written to mark the end of the string. You should try to 
avoid
+   this function because it is very easy to overflow the destination buffer.
+   Use uszprintf instead.

Right. Then don't provide an example!

+   Returns the number of characters written, not including the terminating
+   NULL character.

...null character, it's not the NULL pointer.


+<codeblock>
+      char buffer[10];
+      ...
+      uszprintf(buffer, sizeof(buffer), "Your score is: %d", 
player_score);<endblock>

int player_score;

+@retval
+   Returns the number of characters that would have been written without
+   eventual truncation (like with usprintf), not including the terminating
+   NULL character.

...null character.


 @@int @uvsprintf(char *buf, const char *format, va_list args);
 @xref uconvert, usprintf, uvszprintf
    This is like usprintf(), but you pass the variable argument list 
directly,
-   instead of the arguments themselves.
-   
+   instead of the arguments themselves. You can use this function to 
implement
+   printf like functions, also called variadic functions. You should try to
+   avoid this function because it is very easy to overflow the destination
+   buffer. Use uvszprintf instead.

Then don't put the example here!

Example:
+<codeblock>
+      #include &ltstdarg.h&gt
+
+      void log_message(const char *format, ...)
+      {
+	 char buffer[100];
+	 va_list parameters;
+         
+	 va_start(parameters, format);
+	 uvsprintf(buffer, format, parameters);

va_end(parameters); here.

+	 append_buffer_to_logfile(log_name, buffer);
+	 send_buffer_to_other_networked_players(multicast_ip, buffer);
+	 and_also_print_it_on_the_screen(cool_font, buffer);
+         
+	 va_end(parameters);

Not here.

+      }
+      
+      void some_other_function(void)
+      {
+	 log_message("Hello %s, are you %d years old?\n", "Dave", 25);
+      }<endblock>
+@retval
+   Returns the number of characters written, not including the terminating
+   NULL character.

...null character.


 @@int @uvszprintf(char *buf, int size, const char *format, va_list args);
 @xref uconvert, uszprintf, uvsprintf
    This is like uszprintf(), but you pass the variable argument list
-   directly, instead of the arguments themselves.
+   directly, instead of the arguments themselves. Example:

Put the big example here.

+<codeblock>
+      char buffer[10];
+      ...
+      uvszprintf(buffer, sizeof(buffer), format, parameters);<endblock>
+@retval
+   Returns the number of characters written, not including the terminating
+   NULL character.

No, the number of characters that would have been written... and the null 
character.

-- 
Eric Botcazou