Re: [xml] About libxml2/libxslt documentation

[John Fleck <jfleck inkstain net>]

On Mon, 2004-05-31 at 03:23, pawel praterm com pl wrote:
> I have a proposition that can make the maintaining of docs easier while 
> making it more usefull for users. The proposition is to extend the 
> descriptions of the functions. They should contain such information as:
> - what is the purpose of the function
> - in what situation function should / shouldn't be used
> - does it (or parameters) need any previous initializations
> - what are the possible different API's for making the same thing and 
> what are the differences between them (I think this can be very confusing 
> for users)
> - meaning of special values for params (for example - NULL as a namespace 
> prefix in xmlTextWriterStartElementNS sets default namespace - try to 
> find it in docs)
> - possible reasons of error
> - 'see also' references
> - code example when needed

Pawel -

I think it's great that you want to help with the documentation. I agree
that there's room for improvement, and help is always appreciated.

The best way to approach this is to file bugzilla reports with the
suggested documentation improvements for the API function descriptions.
You don't need to worry about making CVS diffs if that's too much
trouble - the way Daniel has set up the in-line documentation generation
makes it easy for someone with commit access to plop it in.

I appreciate your desire to pursue something broader, but I think it's
best to start within the framework of what now exists.

Cheers,
John