Re: [xml] Documentation improvement suggestion

  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:

  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
paphio:~/XML/doc -> grep '<arg' libxml2-api.xml | grep "\*" | wc -l
paphio:~/XML/doc -> grep '<return' libxml2-api.xml | grep "\*" | wc -l
paphio:~/XML/doc -> grep '<return' libxml2-api.xml | grep "Ptr" | wc -l
paphio:~/XML/doc ->

  so it's around 3000 parameters and return values which would have to
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

  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
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 Veillard      | Red Hat Desktop team
veillard redhat com  | libxml GNOME XML XSLT toolkit | Rpmfind RPM search engine

Oleg Paraschenko  olpa@  XML news in Russian  Generative Programming, XML, TeX, Scheme

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]