Re: [xml] Documentation improvement suggestion

Hi Cory,

the best IMHO would be to go back to gtk-doc, as this has been improved a lot.
But this has been mentioned before ...

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

On 5/7/05, 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 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 Veillard      | Red Hat Desktop team
veillard redhat com  | libxml GNOME XML XSLT toolkit | Rpmfind RPM search engine
xml mailing list, project page
xml gnome org

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