|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r71882 - in branches/release/tools/boostbook: . dtd/1.1 test/doxygen test/doxygen/boost test/more/tests/libs xsl xsl/doxygen
From: dnljms_at_[hidden]
Date: 2011-05-11 19:29:21
Author: danieljames
Date: 2011-05-11 19:29:20 EDT (Wed, 11 May 2011)
New Revision: 71882
URL: http://svn.boost.org/trac/boost/changeset/71882
Log:
Boostbook: merge from trunk.
- Handle more doxygen: \see, tparam, ref (for classes only).
- Modify handling of note so it works for classes as well as functions.
- Automate doxygen test.
- Suppress inspect warning for directory name containing a dot.
Added:
branches/release/tools/boostbook/dtd/1.1/boost-no-inspect
- copied unchanged from r70967, /trunk/tools/boostbook/dtd/1.1/boost-no-inspect
branches/release/tools/boostbook/test/doxygen/autodoc.gold
- copied unchanged from r70967, /trunk/tools/boostbook/test/doxygen/autodoc.gold
Properties modified:
branches/release/tools/boostbook/ (props changed)
Text files modified:
branches/release/tools/boostbook/test/doxygen/Jamfile.v2 | 19 +++++++++
branches/release/tools/boostbook/test/doxygen/boost/example.hpp | 18 +++++++++
branches/release/tools/boostbook/test/more/tests/libs/array.gold | 4 +
branches/release/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl | 77 ++++++++++++++++++++++++++++++++-------
branches/release/tools/boostbook/xsl/reference.xsl | 10 ++++-
branches/release/tools/boostbook/xsl/template.xsl | 23 ++++++++++-
6 files changed, 131 insertions(+), 20 deletions(-)
Modified: branches/release/tools/boostbook/test/doxygen/Jamfile.v2
==============================================================================
--- branches/release/tools/boostbook/test/doxygen/Jamfile.v2 (original)
+++ branches/release/tools/boostbook/test/doxygen/Jamfile.v2 2011-05-11 19:29:20 EDT (Wed, 11 May 2011)
@@ -4,6 +4,7 @@
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
import doxygen ;
+import os ;
doxygen autodoc
:
@@ -12,6 +13,24 @@
<xsl:param>"boost.doxygen.reftitle=Example Reference"
;
+if [ os.name ] = NT
+{
+ actions compare
+ {
+ comp /A $(>[1]) $(>[2]) && echo "Stamped" >$(<)
+ }
+
+}
+else
+{
+ actions compare
+ {
+ diff -u -w $(>[1]) $(>[2]) && echo "Stamped" >$(<)
+ }
+}
+
+make check : autodoc.xml autodoc.gold : @compare ;
+
boostbook standalone
:
example.xml
Modified: branches/release/tools/boostbook/test/doxygen/boost/example.hpp
==============================================================================
--- branches/release/tools/boostbook/test/doxygen/boost/example.hpp (original)
+++ branches/release/tools/boostbook/test/doxygen/boost/example.hpp 2011-05-11 19:29:20 EDT (Wed, 11 May 2011)
@@ -89,11 +89,29 @@
* void foo() {}
* \endcode
*
+ * \tparam TypeParameter A template parameter
+ * \tparam NonTypeParameter This is a non-type template parameter
+ * \tparam TypeParameterWithDefault This is a template parameter with a default argument
*/
template <typename TypeParameter, int NonTypeParameter,
typename TypeParameterWithDefault = int>
struct example_template {};
+
+ /**
+ * \param i A function parameter
+ * \param j Another
+ * \return The answer
+ * \pre i > j
+ *
+ * This is a test function.
+ * \ref example::example "Link to class"
+ * \ref example_template "Link to class template"
+ * \note This is a note.
+ *
+ * \see example::example and example_template
+ */
+ int namespace_func(int i, int j);
}
#define EXAMPLE(m) The macro
Modified: branches/release/tools/boostbook/test/more/tests/libs/array.gold
==============================================================================
--- branches/release/tools/boostbook/test/more/tests/libs/array.gold (original)
+++ branches/release/tools/boostbook/test/more/tests/libs/array.gold 2011-05-11 19:29:20 EDT (Wed, 11 May 2011)
@@ -149,7 +149,9 @@
<phrase role="comment">// <link linkend="id35-bb">modifiers</link></phrase>
<phrase role="keyword">void</phrase> <link linkend="id36-bb"><phrase role="identifier">swap</phrase></link><phrase role="special">(</phrase><link linkend="boost.array">array</link><phrase role="special"><</phrase><phrase role="identifier">T</phrase><phrase role="special">,</phrase> <phrase role="identifier">N</phrase><phrase role="special">></phrase><phrase role="special">&</phrase><phrase role="special">)</phrase><phrase role="special">;</phrase>
<phrase role="keyword">void</phrase> <link linkend="id37-bb"><phrase role="identifier">assign</phrase></link><phrase role="special">(</phrase><phrase role="keyword">const</phrase> <phrase role="identifier">T</phrase><phrase role="special">&</phrase><phrase role="special">)</phrase><phrase role="special">;</phrase>
- <phrase role="identifier">T</phrase> elems[N]<phrase role="special">;</phrase>
+
+ <phrase role="comment">// public data members</phrase>
+ <phrase role="identifier">T</phrase> <phrase role="identifier">elems[N]</phrase><phrase role="special">;</phrase>
<phrase role="special">}</phrase><phrase role="special">;</phrase>
<phrase role="comment">// <link linkend="id38-bb">specialized algorithms</link></phrase>
Modified: branches/release/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl
==============================================================================
--- branches/release/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl (original)
+++ branches/release/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl 2011-05-11 19:29:20 EDT (Wed, 11 May 2011)
@@ -566,6 +566,7 @@
<xsl:template match="param" mode="template">
<xsl:choose>
<xsl:when test="string(type)='class' or string(type)='typename'">
+ <xsl:variable name="name" select="normalize-space(string(declname))"/>
<template-type-parameter>
<xsl:attribute name="name">
<xsl:value-of select="normalize-space(string(declname))"/>
@@ -576,6 +577,13 @@
mode="passthrough"/>
</default>
</xsl:if>
+ <xsl:for-each select="../../detaileddescription//parameterlist[@kind='templateparam']/parameteritem">
+ <xsl:if test="string(parameternamelist/parametername)=$name">
+ <purpose>
+ <xsl:apply-templates select="parameterdescription/para" mode="passthrough"/>
+ </purpose>
+ </xsl:if>
+ </xsl:for-each>
</template-type-parameter>
</xsl:when>
<!-- Doxygen 1.5.8 generates odd xml for template type parameters.
@@ -583,8 +591,11 @@
<xsl:when test="not(declname) and
(starts-with(string(type), 'class ') or starts-with(string(type), 'typename '))">
<template-type-parameter>
- <xsl:attribute name="name">
+ <xsl:variable name="name">
<xsl:value-of select="normalize-space(substring-after(string(type), ' '))"/>
+ </xsl:variable>
+ <xsl:attribute name="name">
+ <xsl:value-of select="$name"/>
</xsl:attribute>
<xsl:if test="defval">
<default>
@@ -592,12 +603,22 @@
mode="passthrough"/>
</default>
</xsl:if>
+ <xsl:for-each select="../../detaileddescription//parameterlist[@kind='templateparam']/parameteritem">
+ <xsl:if test="string(parameternamelist/parametername)=$name">
+ <purpose>
+ <xsl:apply-templates select="parameterdescription/para" mode="passthrough"/>
+ </purpose>
+ </xsl:if>
+ </xsl:for-each>
</template-type-parameter>
</xsl:when>
<xsl:otherwise>
<template-nontype-parameter>
- <xsl:attribute name="name">
+ <xsl:variable name="name">
<xsl:value-of select="normalize-space(string(declname))"/>
+ </xsl:variable>
+ <xsl:attribute name="name">
+ <xsl:value-of select="$name"/>
</xsl:attribute>
<type>
<xsl:apply-templates select="type"/>
@@ -608,6 +629,13 @@
mode="passthrough"/>
</default>
</xsl:if>
+ <xsl:for-each select="../../detaileddescription//parameterlist[@kind='templateparam']/parameteritem">
+ <xsl:if test="string(parameternamelist/parametername)=$name">
+ <purpose>
+ <xsl:apply-templates select="parameterdescription/para" mode="passthrough"/>
+ </purpose>
+ </xsl:if>
+ </xsl:for-each>
</template-nontype-parameter>
</xsl:otherwise>
</xsl:choose>
@@ -1009,12 +1037,6 @@
mode="function-clauses"/>
</throws>
</xsl:if>
- <xsl:variable name="notes" select="*[self::detaileddescription or self::inbodydescription]/para/simplesect[@kind='note' or @kind='attention']"/>
- <xsl:if test="count($notes) > 0">
- <notes>
- <xsl:apply-templates select="$notes" mode="function-clauses"/>
- </notes>
- </xsl:if>
</xsl:template>
<!-- Handle free functions -->
@@ -1254,17 +1276,32 @@
not (@kind='return') and
not (@kind='post') and
not (@kind='attention') and
- not (@kind='note')">
+ not (@kind='see')">
<xsl:apply-templates mode="passthrough"/>
</xsl:if>
</xsl:template>
+ <xsl:template match="para/simplesect[@kind='note' or @kind='attention']" mode="passthrough">
+ <note>
+ <xsl:apply-templates mode="passthrough"/>
+ </note>
+ </xsl:template>
+
<xsl:template match="para/simplesect[@kind='par']" mode="passthrough">
<formalpara>
<xsl:apply-templates mode="passthrough"/>
</formalpara>
</xsl:template>
+ <xsl:template match="para/simplesect[@kind='see']" mode="passthrough">
+ <para>
+ <emphasis role="bold">
+ <xsl:text>See Also:</xsl:text>
+ </emphasis>
+ <xsl:apply-templates mode="passthrough"/>
+ </para>
+ </xsl:template>
+
<xsl:template match="simplesectsep" mode="passthrough">
<xsl:apply-templates mode="passthrough"/>
</xsl:template>
@@ -1315,7 +1352,20 @@
<!-- Ignore ref elements for now, as there is a lot of documentation which
will have incorrect ref elements at the moment -->
<xsl:template match="ref" mode="passthrough">
- <xsl:apply-templates mode="passthrough"/>
+ <xsl:variable name="as-class" select="key('compounds-by-id', @refid)[@kind='class' or @kind='struct']"/>
+ <xsl:choose>
+ <xsl:when test="$as-class">
+ <classname>
+ <xsl:attribute name="alt">
+ <xsl:value-of select="$as-class/compoundname/text()"/>
+ </xsl:attribute>
+ <xsl:value-of select="text()"/>
+ </classname>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:apply-templates mode="passthrough"/>
+ </xsl:otherwise>
+ </xsl:choose>
</xsl:template>
<!-- Handle function clauses -->
@@ -1335,9 +1385,6 @@
<xsl:apply-templates mode="passthrough"/>
</postconditions>
</xsl:if>
- <xsl:if test="@kind='note' or @kind='attention'">
- <xsl:apply-templates mode="passthrough"/>
- </xsl:if>
</xsl:template>
<xsl:template match="parameterlist" mode="function-clauses">
@@ -1353,8 +1400,8 @@
</classname>
<xsl:text> </xsl:text>
<xsl:apply-templates
- select="parameterdescription/para/text()
- |parameterdescription/para/*"
+ select=".//parameterdescription/para/text()
+ |.//parameterdescription/para/*"
mode="passthrough"/>
</xsl:otherwise>
</xsl:choose>
Modified: branches/release/tools/boostbook/xsl/reference.xsl
==============================================================================
--- branches/release/tools/boostbook/xsl/reference.xsl (original)
+++ branches/release/tools/boostbook/xsl/reference.xsl 2011-05-11 19:29:20 EDT (Wed, 11 May 2011)
@@ -160,13 +160,19 @@
<xsl:param name="prefix"/>
<xsl:apply-templates mode="comment">
<xsl:with-param name="wrap"
- select="$wrap and count(*) = 0 and count(text()) = 1"/>
+ select="$wrap and count(text()|*) = 1"/>
<xsl:with-param name="prefix" select="$prefix"/>
</xsl:apply-templates>
</xsl:template>
<xsl:template match="simpara|para" mode="comment">
- <xsl:apply-templates select="text()|*" mode="comment"/>
+ <xsl:param name="wrap" select="false()"/>
+ <xsl:param name="prefix"/>
+ <xsl:apply-templates select="text()|*" mode="comment">
+ <xsl:with-param name="wrap"
+ select="$wrap and count(text()|*) = 1"/>
+ <xsl:with-param name="prefix" select="$prefix"/>
+ </xsl:apply-templates>
</xsl:template>
<xsl:template match="text()" mode="comment">
Modified: branches/release/tools/boostbook/xsl/template.xsl
==============================================================================
--- branches/release/tools/boostbook/xsl/template.xsl (original)
+++ branches/release/tools/boostbook/xsl/template.xsl 2011-05-11 19:29:20 EDT (Wed, 11 May 2011)
@@ -285,11 +285,30 @@
<!-- Display the comment -->
<xsl:if test="$parameter/purpose">
+ <xsl:variable name="param-text">
+ <!-- Display the parameter -->
+ <xsl:call-template name="template.parameter">
+ <xsl:with-param name="parameter" select="$parameter"/>
+ <xsl:with-param name="is-last" select="not($rest)"/>
+ <xsl:with-param name="highlight" select="false()"/>
+ </xsl:call-template>
+ </xsl:variable>
<xsl:call-template name="highlight-comment">
<xsl:with-param name="text">
<xsl:text> // </xsl:text>
- <xsl:apply-templates
- select="$parameter/purpose/*|$parameter/purpose/text()"/>
+ <xsl:apply-templates
+ select="$parameter/purpose/*|$parameter/purpose/text()" mode="comment">
+ <xsl:with-param name="wrap" select="true()"/>
+ <xsl:with-param name="prefix">
+ <xsl:call-template name="indent">
+ <xsl:with-param name="indentation" select="$indentation + string-length($param-text)"/>
+ </xsl:call-template>
+ <xsl:if test="$rest">
+ <xsl:text> </xsl:text>
+ </xsl:if>
+ <xsl:text> // </xsl:text>
+ </xsl:with-param>
+ </xsl:apply-templates>
</xsl:with-param>
</xsl:call-template>
</xsl:if>
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk