Re: [xml] Documentation improvement suggestion

[Daniel Veillard <veillard redhat com>]

On Fri, May 06, 2005 at 11:20:59PM +0400, Oleg A. Paraschenko wrote:
>   Hello,
>
>   I'm a novice in libxml programming, and I'd like the libxml
> documentation was a bit better. In particular, if a function uses
> pointers, it's good to know the following.
>
> 1) Reaction on NULL values
>
> 2) If the caller should use xmlFree()
>
> 3) Side effects related to memory allocation

  Sure, better documentation is always welcome, but look at this:

paphio:~/XML/doc -> grep '<arg' libxml2-api.xml | grep "Ptr" | wc -l
1219
paphio:~/XML/doc -> grep '<arg' libxml2-api.xml | grep "\*" | wc -l
1374
paphio:~/XML/doc -> grep '<return' libxml2-api.xml | grep "\*" | wc -l
175
paphio:~/XML/doc -> grep '<return' libxml2-api.xml | grep "Ptr" | wc -l
347
paphio:~/XML/doc ->

  so it's around 3000 parameters and return values which would have to be
manually checked on all the libxml2 C file headers templates. There is no
way I can answer "yes I will do this" nor "Yes the community will do this".

>   This information reduces risk of writing code like this:
>
> full_name = xmlStrcat(ns_prefix ? ns_prefix : "", local_name);
>
>   (Do you see a coredump here?)

  yes, because I know the behaviour of xmlStrcat(), the input string must
be a memory allocated string and "" will break this assumption. Even if 
the libc strcat() function operates differently, passing "" as the first
argument would also corrupt memory, probably silently though.

  The positive way to make progress on doc issues is not to "it would be
nice if" or "we should do this or that" but to provide an incremental
improvement when you hit a problem. The easiest way is by looking up the
C function header (xmlstring.c around line 500) :

/**
 * xmlStrcat:
 * @cur:  the original xmlChar * array
 * @add:  the xmlChar * array added
 *
 * a strcat for array of xmlChar's. Since they are supposed to be
 * encoded in UTF-8 or an encoding with 8bit based chars, we assume
 * a termination mark of '0'.
 *
 * Returns a new xmlChar * containing the concatenated string.
 */

then making the improvement to the header, and send back a contectual
diff with the change.
If you look at the list archive for last few years, I think I always
applied such documentation improvement feedback nearly immediately.

Daniel

-- 
Daniel Veillard      | Red Hat Desktop team http://redhat.com/
veillard redhat com  | libxml GNOME XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/