boost_mirror/boostbook
1
0
Fork 0
mirror of https://github.com/boostorg/boostbook.git synced 2025-05-09 15:03:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add a workaround for duplicate ids if Doxygen inlines inherited class members.

Browse Source 
When Doxygen option INLINE_INHERITED_MEMB=YES is used, Doxygen generates
duplicate class member definitions with the same ids, when the member is
inherited from a base class. This results in duplicate ids in BoostBook output
and the corresponding errors.

Work around this by checking if the member id starts with the id of the
enclosing class. If it does then the member is assumed to be a genuine member
of the class and we generate a Doxygen id for it. Doxygen refs will point to
this definition of the member. If the member id is different then it must be
an inherited member, and we don't generate a Doxygen id for it. BoostBook
stylesheets will generate a unique id for it, which will be used to link
synopsis to reference of the member in the derived class' documentation.
This commit is contained in:
Andrey Semashev 2024-06-30 17:50:44 +03:00
parent 03120084bb
commit 55bd25054b
1 changed files with 73 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
xsl/doxygen/doxygen2boostbook.xsl
View File

@ -304,6 +304,7 @@
<xsl:template name="enum"> <xsl:template name="enum">
<xsl:param name="in-file"/> <xsl:param name="in-file"/>
<xsl:param name="with-id" select="not(string(@id)='')"/>
<xsl:if test="string(location/attribute::file)=$in-file"> <xsl:if test="string(location/attribute::file)=$in-file">
<xsl:variable name="name"> <xsl:variable name="name">
@ -313,7 +314,7 @@
</xsl:variable> </xsl:variable>
<enum> <enum>
<xsl:if test="not(string(@id)='')"> <xsl:if test="$with-id">
<xsl:attribute name="id"> <xsl:attribute name="id">
<xsl:value-of select="concat($doxygen-id-prefix, @id)"/> <xsl:value-of select="concat($doxygen-id-prefix, @id)"/>
</xsl:attribute> </xsl:attribute>
@ -323,7 +324,9 @@
<xsl:value-of select="$name"/> <xsl:value-of select="$name"/>
</xsl:attribute> </xsl:attribute>
<xsl:apply-templates select="enumvalue"/> <xsl:apply-templates select="enumvalue">
<xsl:with-param name="with-id" select="$with-id"/>
</xsl:apply-templates>
<xsl:apply-templates select="briefdescription" mode="passthrough"/> <xsl:apply-templates select="briefdescription" mode="passthrough"/>
<xsl:apply-templates select="detaileddescription" mode="passthrough"/> <xsl:apply-templates select="detaileddescription" mode="passthrough"/>
@ -334,6 +337,8 @@
</xsl:template> </xsl:template>
<xsl:template match="enumvalue"> <xsl:template match="enumvalue">
<xsl:param name="with-id" select="not(string(@id)='')"/>
<xsl:choose> <xsl:choose>
<!-- If the string INTERNAL ONLY is in the description, don't <!-- If the string INTERNAL ONLY is in the description, don't
emit this entity. This hack is necessary because Doxygen doesn't emit this entity. This hack is necessary because Doxygen doesn't
@ -344,7 +349,7 @@
<xsl:otherwise> <xsl:otherwise>
<enumvalue> <enumvalue>
<xsl:if test="not(string(@id)='')"> <xsl:if test="$with-id">
<xsl:attribute name="id"> <xsl:attribute name="id">
<xsl:value-of select="concat($doxygen-id-prefix, @id)"/> <xsl:value-of select="concat($doxygen-id-prefix, @id)"/>
</xsl:attribute> </xsl:attribute>
@ -602,11 +607,11 @@
</xsl:when> </xsl:when>
<xsl:when test="@kind='variable'"> <xsl:when test="@kind='variable'">
<xsl:call-template name="variable" /> <xsl:call-template name="variable"/>
</xsl:when> </xsl:when>
<xsl:when test="@kind='enum'"> <xsl:when test="@kind='enum'">
<xsl:call-template name="enum" /> <xsl:call-template name="enum"/>
</xsl:when> </xsl:when>
<xsl:otherwise> <xsl:otherwise>
@ -963,6 +968,25 @@
<xsl:param name="in-section" select="false()"/> <xsl:param name="in-section" select="false()"/>
<xsl:param name="in-file" select="''"/> <xsl:param name="in-file" select="''"/>
<!-- Workaround for INLINE_INHERITED_MEMB=YES Doxygen parameter. In this mode, Doxygen
duplicates base class members in the derived classes, with the same ids. This results
in duplicate ids in the resulting BoostBook tags.
To avoid this, check if the member id starts with the id of the enclosing class, and
only generate an id in the output if it does. Otherwise, assume this is an inherited
member, and an id for it is generated in the definition of the base class. Doxygen refs
will point to the member definition in the base class, while for the definition in the
derived class BoostBook stylesheets will generate a unique id that will be used to
link synopsis to the reference of the member. -->
<xsl:variable name="parent-compounddef" select="ancestor::compounddef[last()]"/>
<xsl:variable name="parent-class-id">
<xsl:if test="$parent-compounddef/attribute::kind='class' or
$parent-compounddef/attribute::kind='struct' or
$parent-compounddef/attribute::kind='union'">
<xsl:value-of select="$parent-compounddef/attribute::id"/>
</xsl:if>
</xsl:variable>
<xsl:variable name="with-id" select="not(string(@id)='') and ($parent-class-id='' or starts-with(string(@id), $parent-class-id))"/>
<xsl:choose> <xsl:choose>
<!-- If the string INTERNAL ONLY is in the description, don't <!-- If the string INTERNAL ONLY is in the description, don't
emit this entity. This hack is necessary because Doxygen doesn't emit this entity. This hack is necessary because Doxygen doesn't
@ -974,6 +998,7 @@
<xsl:when test="@kind='typedef'"> <xsl:when test="@kind='typedef'">
<xsl:call-template name="typedef"> <xsl:call-template name="typedef">
<xsl:with-param name="in-file" select="$in-file"/> <xsl:with-param name="in-file" select="$in-file"/>
<xsl:with-param name="with-id" select="$with-id"/>
</xsl:call-template> </xsl:call-template>
</xsl:when> </xsl:when>
<xsl:when test="@kind='function'"> <xsl:when test="@kind='function'">
@ -1006,23 +1031,33 @@
<xsl:choose> <xsl:choose>
<xsl:when test="string(name/text())=$in-class"> <xsl:when test="string(name/text())=$in-class">
<xsl:call-template name="constructor"/> <xsl:call-template name="constructor">
<xsl:with-param name="with-id" select="$with-id"/>
</xsl:call-template>
</xsl:when> </xsl:when>
<xsl:when test="string(name/text())=concat('~',$in-class)"> <xsl:when test="string(name/text())=concat('~',$in-class)">
<xsl:call-template name="destructor"/> <xsl:call-template name="destructor">
<xsl:with-param name="with-id" select="$with-id"/>
</xsl:call-template>
</xsl:when> </xsl:when>
<xsl:when test="string(name/text())='operator='"> <xsl:when test="string(name/text())='operator='">
<xsl:call-template name="copy-assignment"/> <xsl:call-template name="copy-assignment">
<xsl:with-param name="with-id" select="$with-id"/>
</xsl:call-template>
</xsl:when> </xsl:when>
<xsl:when test="normalize-space(string(type))='' <xsl:when test="normalize-space(string(type))=''
and contains(name/text(), 'operator ')"> and contains(name/text(), 'operator ')">
<xsl:if test="$in-section"> <xsl:if test="$in-section">
<xsl:call-template name="conversion-operator"/> <xsl:call-template name="conversion-operator">
<xsl:with-param name="with-id" select="$with-id"/>
</xsl:call-template>
</xsl:if> </xsl:if>
</xsl:when> </xsl:when>
<xsl:otherwise> <xsl:otherwise>
<xsl:if test="$in-section"> <xsl:if test="$in-section">
<xsl:call-template name="method"/> <xsl:call-template name="method">
<xsl:with-param name="with-id" select="$with-id"/>
</xsl:call-template>
</xsl:if> </xsl:if>
</xsl:otherwise> </xsl:otherwise>
</xsl:choose> </xsl:choose>
@ -1031,17 +1066,21 @@
</xsl:when> </xsl:when>
<xsl:when test="@kind='friend'"> <xsl:when test="@kind='friend'">
<xsl:if test="./detaileddescription/para or ./briefdescription/para"> <xsl:if test="./detaileddescription/para or ./briefdescription/para">
<xsl:call-template name="method"/> <xsl:call-template name="method">
<xsl:with-param name="with-id" select="$with-id"/>
</xsl:call-template>
</xsl:if> </xsl:if>
</xsl:when> </xsl:when>
<xsl:when test="@kind='enum'"> <xsl:when test="@kind='enum'">
<xsl:call-template name="enum"> <xsl:call-template name="enum">
<xsl:with-param name="in-file" select="$in-file"/> <xsl:with-param name="in-file" select="$in-file"/>
<xsl:with-param name="with-id" select="$with-id"/>
</xsl:call-template> </xsl:call-template>
</xsl:when> </xsl:when>
<xsl:when test="@kind='variable'"> <xsl:when test="@kind='variable'">
<xsl:call-template name="variable"> <xsl:call-template name="variable">
<xsl:with-param name="in-file" select="$in-file"/> <xsl:with-param name="in-file" select="$in-file"/>
<xsl:with-param name="with-id" select="$with-id"/>
</xsl:call-template> </xsl:call-template>
</xsl:when> </xsl:when>
<xsl:otherwise> <xsl:otherwise>
@ -1055,11 +1094,12 @@
<!-- Display typedefs --> <!-- Display typedefs -->
<xsl:template name="typedef"> <xsl:template name="typedef">
<xsl:param name="in-file" select="''"/> <xsl:param name="in-file" select="''"/>
<xsl:param name="with-id" select="not(string(@id)='')"/>
<xsl:if test="string(location/attribute::file)=$in-file"> <xsl:if test="string(location/attribute::file)=$in-file">
<!-- TBD: Handle public/protected/private --> <!-- TBD: Handle public/protected/private -->
<typedef> <typedef>
<xsl:if test="not(string(@id)='')"> <xsl:if test="$with-id">
<xsl:attribute name="id"> <xsl:attribute name="id">
<xsl:value-of select="concat($doxygen-id-prefix, @id)"/> <xsl:value-of select="concat($doxygen-id-prefix, @id)"/>
</xsl:attribute> </xsl:attribute>
@ -1341,6 +1381,7 @@
<!-- Handle free functions --> <!-- Handle free functions -->
<xsl:template name="function"> <xsl:template name="function">
<xsl:param name="in-file" select="''"/> <xsl:param name="in-file" select="''"/>
<xsl:param name="with-id" select="not(string(@id)='')"/>
<xsl:variable name="firstpara" <xsl:variable name="firstpara"
select="normalize-space(detaileddescription/para[1])"/> select="normalize-space(detaileddescription/para[1])"/>
@ -1366,7 +1407,7 @@
<xsl:choose> <xsl:choose>
<xsl:when test="not(contains($has-overload, 'false'))"> <xsl:when test="not(contains($has-overload, 'false'))">
<overloaded-function> <overloaded-function>
<xsl:if test="not(string(@id)='')"> <xsl:if test="$with-id">
<xsl:attribute name="id"> <xsl:attribute name="id">
<xsl:value-of select="concat($doxygen-id-prefix, @id)"/> <xsl:value-of select="concat($doxygen-id-prefix, @id)"/>
</xsl:attribute> </xsl:attribute>
@ -1384,7 +1425,7 @@
</xsl:when> </xsl:when>
<xsl:otherwise> <xsl:otherwise>
<function> <function>
<xsl:if test="not(string(@id)='')"> <xsl:if test="$with-id">
<xsl:attribute name="id"> <xsl:attribute name="id">
<xsl:value-of select="concat($doxygen-id-prefix, @id)"/> <xsl:value-of select="concat($doxygen-id-prefix, @id)"/>
</xsl:attribute> </xsl:attribute>
@ -1438,8 +1479,10 @@
<!-- Handle constructors --> <!-- Handle constructors -->
<xsl:template name="constructor"> <xsl:template name="constructor">
<xsl:param name="with-id" select="not(string(@id)='')"/>
<constructor> <constructor>
<xsl:if test="not(string(@id)='')"> <xsl:if test="$with-id">
<xsl:attribute name="id"> <xsl:attribute name="id">
<xsl:value-of select="concat($doxygen-id-prefix, @id)"/> <xsl:value-of select="concat($doxygen-id-prefix, @id)"/>
</xsl:attribute> </xsl:attribute>
@ -1455,8 +1498,10 @@
<!-- Handle Destructors --> <!-- Handle Destructors -->
<xsl:template name="destructor"> <xsl:template name="destructor">
<xsl:param name="with-id" select="not(string(@id)='')"/>
<destructor> <destructor>
<xsl:if test="not(string(@id)='')"> <xsl:if test="$with-id">
<xsl:attribute name="id"> <xsl:attribute name="id">
<xsl:value-of select="concat($doxygen-id-prefix, @id)"/> <xsl:value-of select="concat($doxygen-id-prefix, @id)"/>
</xsl:attribute> </xsl:attribute>
@ -1469,8 +1514,10 @@
<!-- Handle Copy Assignment --> <!-- Handle Copy Assignment -->
<xsl:template name="copy-assignment"> <xsl:template name="copy-assignment">
<xsl:param name="with-id" select="not(string(@id)='')"/>
<copy-assignment> <copy-assignment>
<xsl:if test="not(string(@id)='')"> <xsl:if test="$with-id">
<xsl:attribute name="id"> <xsl:attribute name="id">
<xsl:value-of select="concat($doxygen-id-prefix, @id)"/> <xsl:value-of select="concat($doxygen-id-prefix, @id)"/>
</xsl:attribute> </xsl:attribute>
@ -1488,8 +1535,10 @@
<!-- Handle conversion operator --> <!-- Handle conversion operator -->
<xsl:template name="conversion-operator"> <xsl:template name="conversion-operator">
<xsl:param name="with-id" select="not(string(@id)='')"/>
<method> <method>
<xsl:if test="not(string(@id)='')"> <xsl:if test="$with-id">
<xsl:attribute name="id"> <xsl:attribute name="id">
<xsl:value-of select="concat($doxygen-id-prefix, @id)"/> <xsl:value-of select="concat($doxygen-id-prefix, @id)"/>
</xsl:attribute> </xsl:attribute>
@ -1512,8 +1561,10 @@
<!-- Handle methods --> <!-- Handle methods -->
<xsl:template name="method"> <xsl:template name="method">
<xsl:param name="with-id" select="not(string(@id)='')"/>
<method> <method>
<xsl:if test="not(string(@id)='')"> <xsl:if test="$with-id">
<xsl:attribute name="id"> <xsl:attribute name="id">
<xsl:value-of select="concat($doxygen-id-prefix, @id)"/> <xsl:value-of select="concat($doxygen-id-prefix, @id)"/>
</xsl:attribute> </xsl:attribute>
@ -1537,9 +1588,11 @@
<!-- Handle member variables --> <!-- Handle member variables -->
<xsl:template name="variable"> <xsl:template name="variable">
<xsl:param name="in-file"/> <xsl:param name="in-file"/>
<xsl:param name="with-id" select="not(string(@id)='')"/>
<xsl:if test="string(location/attribute::file)=$in-file"> <xsl:if test="string(location/attribute::file)=$in-file">
<data-member> <data-member>
<xsl:if test="not(string(@id)='')"> <xsl:if test="$with-id">
<xsl:attribute name="id"> <xsl:attribute name="id">
<xsl:value-of select="concat($doxygen-id-prefix, @id)"/> <xsl:value-of select="concat($doxygen-id-prefix, @id)"/>
</xsl:attribute> </xsl:attribute>