API reference manual generation ?

I'm once again trying to understand how to generate an API reference
manual (for various languages) in docbook.

I started by copying directly from
http://docbook.org/tdg/en/html/ch02.html#making-refentry, then processed
with the 1.72 XSL stylesheets. Looking at the generated html, I'm not
sure what to make of what I see. It looks neither syntactically correct,
nor does it look suitable for a reference manual. Is this output
expected / correct ?
(Both, input, as well as output are attached.)


But more to my actual question: what is the best markup to use for a
function for which I'd like to document

- general usage (requirements, effects, results)
- arguments

i.e. something akin to, say,
http://boost.org/libs/python/doc/v2/class.html ?


Thanks,
		Stefan

-- 

      ...ich hab' noch einen Koffer in Berlin...