Re: [xml] About libxml2/libxslt documentation

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.


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