Re: [AD] Documentation update

[Eric B. <ebo...@li...>]

> It benefits newbies who get a RTFM with a pointer to the
> documentation. They can jump directly to the definition of other
> allegro functions they might not know yet.

I'm not convinced. Don't forget that the docs is not generated only in HTML 
form. For example, the references are translated as "SEE ALSO" entries in 
the man pages and I don't see why the "SEE ALSO" line for 'ustrcpy' should 
contain 'allegro_message'.

> It is only one example. The repetitive use of ugetx without variation
> of the parameter shows the side effect nature of the function. A
> different type for `p' doesn't seem to be enough of a problem to
> require another example.

Agreed.


Now to the nits :-)

@@ -971,9 +981,12 @@
 @@int @uoffset(const char *s, int index);
 @xref ugetat, usetat, uinsert, uremove
    Finds out the offset (in bytes from the start of the string) of the
-   character at the specified index in the string s. If the index is 
negative,
+   character at the specified index in the string s. 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 an offset to the last character.
+   return an offset to the last character. Example:
+<codeblock>
+      int *from_third_letter = uoffset(text_string, 2);<endblock>
 @retval
    Returns the offset in bytes to the specified character.
 
Still not the right type!


+@xref allegro_message, ustrncpy
 @eref exgui
    This function retrieves tokens from s which are delimited by characters
    from set. To initiate the search, pass the string to be searched as s.
    For the remaining tokens, pass NULL instead. Warning: Since ustrtok 
alters
    the string it is parsing, you should always copy the string to a 
temporary
    buffer before parsing it. Also, this function is not reentrant (ie. you
-   cannot parse two strings at the same time).
+   cannot parse two strings at the same time). Example:
+<codeblock>
+      char *word;
+      char string[50];
+      ustrncpy(string, "some-words with dashes", sizeof(string));
+      word = ustrtok(string, " -");
+      while (word) {
+	 allegro_message("Found `%s'\n", word);
+	 word = ustrtok(NULL, " -");
+      }<endblock>
 @retval
    Returns a pointer to the token, or NULL if no more are found.

You still don't explicitly copy the string to a temporary:

	char string[]="some-words with dashes";
        char *temp = ustrdup(string);
        ...
        free (temp);


 @@char *@ustrtok_r(char *s, const char *set, char **last);
-@xref ustrtok
+@xref ustrtok, allegro_message
    Reentrant version of ustrtok. The last parameter is used to keep track
    of where the parsing is up to and must be a pointer to a char * variable
    allocated by the user that remains the same while parsing the same
-   string.
+   string. Example:
+<codeblock>
+      char *word, *last;
+      char string[50];
+      ustrncpy(string, "some-words with dashes", sizeof(string));
+      word = ustrtok_r(string, " -", &last);
+      while (word) {
+	 allegro_message("Found `%s'\n", word);
+	 word = ustrtok_r(NULL, " -", &last);
+      }<endblock>
 @retval

Likewise.


-- 
Eric Botcazou