We have plenty of generic typedefs (that basically just alias a
struct, or our popular virXXXPtr). Because we do not generate
HTML docs for it, the documentation is placed at random places,
e.g.: comment from virDomainPtr typedef ("a virDomainPtr is
pointer to a virDomain private structure ...") ends up after
virDomainProcessSignal enum block.

There are some less weird occurrences of this problem (e.g.
virBlkioParameterPtr), but yet - the typedef appears in TOC.

Therefore, generate a block for each typedef and put its
description there.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
---
 docs/newapi.xsl | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/newapi.xsl b/docs/newapi.xsl
index a8797f800d..3ddcc27d96 100644
--- a/docs/newapi.xsl
+++ b/docs/newapi.xsl
@@ -324,6 +324,26 @@
     </div>
   </xsl:template>
 
+  <xsl:template match="typedef">
+    <xsl:variable name="name" select="string(@name)"/>
+    <xsl:variable name="type" select="string(@type)"/>
+    <h3><a id="{$name}"><code><xsl:value-of select="$name"/></code></a></h3>
+    <div class="api">
+      <pre>
+        <span class="keyword">typedef</span><xsl:text> </xsl:text>
+        <xsl:value-of select="$type"/>
+        <xsl:text> </xsl:text>
+        <xsl:value-of select="$name"/>
+        <xsl:text>;</xsl:text>
+      </pre>
+    </div>
+    <div class="description">
+    <xsl:call-template name="formattext">
+      <xsl:with-param name="text" select="info"/>
+    </xsl:call-template>
+    </div>
+  </xsl:template>
+
   <xsl:template match="struct" mode="toc">
     <span class="keyword">typedef</span><xsl:text> </xsl:text>
     <span class="type"><xsl:value-of select="@type"/></span>
-- 
2.39.3

On Wed, May 24, 2023 at 18:21:05 +0200, Michal Privoznik wrote:
> We have plenty of generic typedefs (that basically just alias a
> struct, or our popular virXXXPtr). Because we do not generate
> HTML docs for it, the documentation is placed at random places,
> e.g.: comment from virDomainPtr typedef ("a virDomainPtr is
> pointer to a virDomain private structure ...") ends up after
> virDomainProcessSignal enum block.
> 
> There are some less weird occurrences of this problem (e.g.
> virBlkioParameterPtr), but yet - the typedef appears in TOC.
> 
> Therefore, generate a block for each typedef and put its
> description there.
> 
> Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
> ---
>  docs/newapi.xsl | 20 ++++++++++++++++++++
>  1 file changed, 20 insertions(+)
> 
> diff --git a/docs/newapi.xsl b/docs/newapi.xsl
> index a8797f800d..3ddcc27d96 100644
> --- a/docs/newapi.xsl
> +++ b/docs/newapi.xsl
> @@ -324,6 +324,26 @@
>      </div>
>    </xsl:template>
>  
> +  <xsl:template match="typedef">
> +    <xsl:variable name="name" select="string(@name)"/>
> +    <xsl:variable name="type" select="string(@type)"/>
> +    <h3><a id="{$name}"><code><xsl:value-of select="$name"/></code></a></h3>

Here you generate an anchor with ID of the '*Ptr' name, but there is
already one generated by the mode='toc' template for 'typedef'.

If you change the 'id' attribute to 'href' in the TOC generator it
should work properly.


> +    <div class="api">
> +      <pre>
> +        <span class="keyword">typedef</span><xsl:text> </xsl:text>
> +        <xsl:value-of select="$type"/>
> +        <xsl:text> </xsl:text>
> +        <xsl:value-of select="$name"/>
> +        <xsl:text>;</xsl:text>
> +      </pre>
> +    </div>
> +    <div class="description">
> +    <xsl:call-template name="formattext">
> +      <xsl:with-param name="text" select="info"/>
> +    </xsl:call-template>
> +    </div>
> +  </xsl:template>
> +
>    <xsl:template match="struct" mode="toc">
>      <span class="keyword">typedef</span><xsl:text> </xsl:text>
>      <span class="type"><xsl:value-of select="@type"/></span>

I'm wondering what actually happened that resulted in printing/matching
the <info> tag into [not so] randomly (it was placed sorted
alphabetically in the place where your template now generates it
properly because nothing seems to format the <info> tag by default.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>