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

There are/can be overall docs for enums (e.g. virDomainModificationImpact) not just individual values. But these never make it into the generated HTML which is a bit unfortunate as they can contain valuable information for users. Generate a block with overall enum documentation, just like we do for functions. Signed-off-by: Michal Privoznik <mprivozn@redhat.com> --- docs/newapi.xsl | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/newapi.xsl b/docs/newapi.xsl index 3ddcc27d96..56bed1ef6a 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -286,6 +286,11 @@ <xsl:template match="typedef[@type = 'enum']"> <xsl:variable name="name" select="string(@name)"/> <h3><a id="{$name}"><code><xsl:value-of select="$name"/></code></a></h3> + <div class="description"> + <xsl:call-template name="formattext"> + <xsl:with-param name="text" select="info"/> + </xsl:call-template> + </div> <div class="api"> <pre> <span class="keyword">enum</span><xsl:text> </xsl:text> -- 2.39.3

I was approached by a KubeVirt developer to clarify what value does VIR_DOMAIN_MEMORY_STAT_DISK_CACHES report, whether it's from the guest or the host POV. And since I didn't know the answer even after reading the docs I think we can do better. Clarify the POV then. Signed-off-by: Michal Privoznik <mprivozn@redhat.com> --- include/libvirt/libvirt-domain.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h index 3312b8339e..20467849a4 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -709,7 +709,8 @@ typedef virDomainInterfaceStatsStruct *virDomainInterfaceStatsPtr; /** * virDomainMemoryStatTags: * - * Memory Statistics Tags: + * These represent values from inside of the guest (e.g. the same value would + * be read from '/proc/meminfo' and/or other files from inside the guest). * * Since: 0.7.5 */ -- 2.39.3