diff options
author | Peter Hutterer <peter.hutterer@who-t.net> | 2013-04-02 10:09:11 +1000 |
---|---|---|
committer | Kristian Høgsberg <krh@bitplanet.net> | 2013-04-03 15:44:49 -0400 |
commit | b17e5e1615a17f6cb3f5112a822d6f3f07738095 (patch) | |
tree | b09e2f164085d86e4de08f0be6e1493ba9eb6d74 /doc | |
parent | 378caae828afeb4075a1e98db1d1eaca489a58d5 (diff) |
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>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Wayland/doxygen-to-publican.xsl | 95 |
1 files changed, 92 insertions, 3 deletions
diff --git a/doc/Wayland/doxygen-to-publican.xsl b/doc/Wayland/doxygen-to-publican.xsl index 2e3ec5d..864237c 100644 --- a/doc/Wayland/doxygen-to-publican.xsl +++ b/doc/Wayland/doxygen-to-publican.xsl @@ -35,17 +35,106 @@ </section> </xsl:template> +<xsl:template match="parameteritem"> + <varlistentry> + <term> + <xsl:value-of select="parameternamelist/parametername"/> + </term> + <listitem> + <para> + <xsl:value-of select="parameterdescription/para"/> + </para> + </listitem> + </varlistentry> +</xsl:template> + +<xsl:template match="parameterlist"> + <xsl:if test="parameteritem"> + <variablelist> + <xsl:apply-templates select="parameteritem" /> + </variablelist> + </xsl:if> +</xsl:template> + +<xsl:template match="ref"> + <emphasis><xsl:value-of select="." /></emphasis> +</xsl:template> + +<xsl:template match="simplesect[@kind='return']"> + <variablelist> + <varlistentry> + <term>Returns:</term> + <listitem> + <para> + <xsl:value-of select="." /> + </para> + </listitem> + </varlistentry> + </variablelist> +</xsl:template> + +<xsl:template match="simplesect[@kind='see']"> + <itemizedlist> + <listitem> + <para> + See also: + <xsl:for-each select="para/ref"> + <emphasis><xsl:value-of select="."/><xsl:text> </xsl:text></emphasis> + </xsl:for-each> + </para> + </listitem> + </itemizedlist> +</xsl:template> + +<xsl:template match="simplesect[@kind='since']"> + <itemizedlist> + <listitem> + <para> + Since: <xsl:value-of select="para"/> + </para> + </listitem> + </itemizedlist> +</xsl:template> + +<xsl:template match="simplesect[@kind='note']"> + <emphasis>Note: <xsl:value-of select="."/></emphasis> +</xsl:template> + +<xsl:template match="programlisting"> + <programlisting><xsl:value-of select="."/></programlisting> +</xsl:template> + +<!-- this opens a para for each detaileddescription/para. I could not find a + way to extract the right text for the description from the + source otherwise. Downside: we can't use para for return value, "see + also", etc. because they're already inside a para. So they're lists. + + It also means we don't control the order of when something is added to + the output, it matches the input file + --> +<xsl:template match="detaileddescription/para"> + <para><xsl:apply-templates /></para> +</xsl:template> + +<xsl:template match="detaileddescription"> + <xsl:apply-templates select="para" /> +</xsl:template> <!-- methods --> <xsl:template match="memberdef" > - <xsl:if test="@kind = 'function' and @static = 'no'"> + <xsl:if test="@kind = 'function' and @static = 'no'"> <varlistentry> <term> - <xsl:value-of select="name" /> + <xsl:value-of select="name"/> - <xsl:value-of select="briefdescription" /> </term> <listitem> - <para></para> + <para> + <synopsis> + <xsl:value-of select="definition"/><xsl:value-of select="argsstring"/> + </synopsis> + </para> + <xsl:apply-templates select="detaileddescription" /> </listitem> </varlistentry> </xsl:if> |