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@xxxxxxxxxx>
> ---
> 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@xxxxxxxxxx>
