Re: [xml] Documentation improvement suggestion

["Oleg A. Paraschenko" <olpa xmlhack ru>]

  Hello Daniel,

  thank you for replying.

On Sat, 7 May 2005 09:30:37 -0400
Daniel Veillard <veillard redhat com> wrote:

> 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".

  Yes, I knew this answer in advance. It's impossible to add annotations
to all existing functions. However, it's good if possible to add notes
when writing new code.

> >   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.

  Sorry, the example is not very good due to using "". In the actual
program I used a static buffer of an appropriate size.

>   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.

  I'll do it when I can.

> If you look at the list archive for last few years, I think I always
> applied such documentation improvement feedback nearly immediately.

  Thank you again for comments.

> 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/


-- 
Oleg Paraschenko  olpa@ http://xmlhack.ru/  XML news in Russian
http://uucode.com/blog/  Generative Programming, XML, TeX, Scheme