[xml] About libxml2/libxslt documentation

[pawel praterm com pl]

Hi,
Im'm a user of libxml2/libxslt and, while both libraries are just what 
they should to be, the documentation, from the user point of view, is 
poor. All the API is focused on functions, but the doc isn't. Function 
description usually doesn't provide more information that can be guessed 
from function's and parameters' name. If I need more information I have to 
search through quite chaotic set of tutorials, module overviews and code 
examples. Usually they are a little outdated compared to code. And usually 
I end up with xmllint/xsltproc code ;-). I think it is not what users 
want.

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

Users should be able to get information they want much faster - you just 
need to know some names of functions that you think you need ;-). And 
because of 'see also' and 'different API' references you can start 
browsing the documentation from any point. A good example of such 
documentation is wxWidgets manual - see 
http://www.wxwidgets.org/manuals/2.4.2/wx62.htm#wxcmdlineparser
for example (in wxWigets situation is a little simplier because its 
C++...)

Maintainig such informations shouldn't be very difficult for developers - 
if you are changing the code of function, you can also take a look at 
function docs and spare three minutes to check if it is up-to-date. It is 
easier then checking if all the tutorials and other resources are OK.

And the last proposition - let's use the WIKI'like tool for maintaining 
this documentation. libxml2 has many users and at least some of them would 
like to help improving the library. But checking the CVS, making diffs and 
sending patches to group (you have to be subscribed) ? - it's too much 
work if you just want to add a sentence to function description.

In that way we can have really extensive, up-to-date and user-friendly 
documentation in few months.

If something in unclear it can be because of my English...

Best regards
Paul Palucha

http://www.praterm.pl
http://www.szarp.com.pl