Re: [xml] Documentation improvement suggestion

[Cory Nelson <phrosty gmail com>]

I think a much easier improvement would be a new color scheme and less
boxes.  The current one is so cluttered it makes it very hard to skim
through.

On 5/7/05, 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".
> 
> >   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/
> _______________________________________________
> xml mailing list, project page  http://xmlsoft.org/
> xml gnome org
> http://mail.gnome.org/mailman/listinfo/xml
> 


-- 
Cory Nelson
http://www.int64.org