doc: improve formatting of client-side documentation

A bunch of changes to the xsl transformation stylesheet to make Chapter 4
(Client API) look nicer and more readable.

Main changes:
- function synopsis listed
- lists for parameters and return values
- long function descriptions
- misc other hooks for "see also", "note", etc

The long description is a sore point. doxygen xml output is difficult to
parse with the output being in the form of
<detailed description>
  <para>
  	<parameterlist> .... </parameterlist>
	<simplesect kind="return">... </simplesect>
	First paragraph of long description
  </para>
  <para>
  	Second paragraph of long <sometag>description</sometag>
  </para>
</detaileddescription>

So we need to ignore parameterlist and simplesect, but extract the text from
everything else. Any improvements on that welcome.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>