Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r70863 - in trunk/tools/boostbook: test/doxygen test/doxygen/boost xsl xsl/doxygen
From: steven_at_[hidden]
Date: 2011-04-02 13:35:14


Author: steven_watanabe
Date: 2011-04-02 13:35:13 EDT (Sat, 02 Apr 2011)
New Revision: 70863
URL: http://svn.boost.org/trac/boost/changeset/70863

Log:
Handle more Doxygen elements: tparam, ref (for classes only), Modify handling of note so it works for classes as well as functions.
Text files modified:
   trunk/tools/boostbook/test/doxygen/Jamfile.v2 | 4 +-
   trunk/tools/boostbook/test/doxygen/autodoc.gold | 13 +++++--
   trunk/tools/boostbook/test/doxygen/boost/example.hpp | 16 +++++++++
   trunk/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl | 66 +++++++++++++++++++++++++++++++--------
   trunk/tools/boostbook/xsl/reference.xsl | 10 ++++-
   trunk/tools/boostbook/xsl/template.xsl | 23 ++++++++++++-
   6 files changed, 108 insertions(+), 24 deletions(-)

Modified: trunk/tools/boostbook/test/doxygen/Jamfile.v2
==============================================================================
--- trunk/tools/boostbook/test/doxygen/Jamfile.v2 (original)
+++ trunk/tools/boostbook/test/doxygen/Jamfile.v2 2011-04-02 13:35:13 EDT (Sat, 02 Apr 2011)
@@ -17,7 +17,7 @@
 {
     actions compare
     {
- comp /A $(>[1]) $(>[2]) >$(<)
+ comp /A $(>[1]) $(>[2]) && echo "Stamped" >$(<)
     }
 
 }
@@ -25,7 +25,7 @@
 {
     actions compare
     {
- diff -u $(>[1]) $(>[2]) >$(<)
+ diff -u $(>[1]) $(>[2]) && echo "Stamped" >$(<)
     }
 }
 

Modified: trunk/tools/boostbook/test/doxygen/autodoc.gold
==============================================================================
--- trunk/tools/boostbook/test/doxygen/autodoc.gold (original)
+++ trunk/tools/boostbook/test/doxygen/autodoc.gold 2011-04-02 13:35:13 EDT (Sat, 02 Apr 2011)
@@ -1,8 +1,8 @@
 <?xml version="1.0" standalone="yes"?>
 <library-reference id="example_reference"><title>Example Reference</title><header name="boost/example.hpp"><namespace name="example"><class name="example"><purpose>Documentation for class example. </purpose><class name="inner_class"><data-member name="x"><type>int</type></data-member></class><enum name="class_enum"><enumvalue name="enumerator"/></enum><data-member name="integer"><type>int</type></data-member><data-member name="mutable_integer" specifiers="mutable"><type>int</type></data-member><data-member name="const_integer"><type>const int</type></data-member><data-member name="static_integer" specifiers="static"><type>int</type></data-member><data-member name="static_const_integer" specifiers="static"><type>const int</type></data-member></class><struct name="example_template"><template>
- <template-type-parameter name="TypeParameter"/>
- <template-nontype-parameter name="NonTypeParameter"><type>int</type></template-nontype-parameter>
- <template-type-parameter name="TypeParameterWithDefault"><default>int</default></template-type-parameter>
+ <template-type-parameter name="TypeParameter"><purpose><para>A template parameter </para></purpose></template-type-parameter>
+ <template-nontype-parameter name="NonTypeParameter"><type>int</type><purpose><para>This is a non-type template parameter </para></purpose></template-nontype-parameter>
+ <template-type-parameter name="TypeParameterWithDefault"><default>int</default><purpose><para>This is a template parameter with a default argument </para></purpose></template-type-parameter>
     </template><description><para>Test some doxygen markup</para><para>Embedded docbook list:</para><para>
  <orderedlist><listitem><simpara>1</simpara></listitem><listitem><simpara>2</simpara></listitem></orderedlist>
  </para><para><emphasis>Special</emphasis> <emphasis role="bold">Bold</emphasis> <computeroutput>Typewriter</computeroutput> <emphasis>Italics</emphasis> <emphasis>emphasis</emphasis> <computeroutput>parameter</computeroutput> </para><para><itemizedlist>
@@ -15,4 +15,9 @@
 </itemizedlist>
 Line 1<sbr/>
  Line 2</para><para><programlisting> void foo() {}
-</programlisting> </para></description></struct><enum name="namespace_enum"><enumvalue name="enumerator"/></enum><data-member name="namespace_integer"><type>int</type></data-member><data-member name="namespace_static_integer" specifiers="static"><type>int</type></data-member><data-member name="namespace_const_integer"><type>const int</type></data-member><data-member name="namespace_static_const_integer" specifiers="static"><type>const int</type></data-member></namespace><macro name="EXAMPLE" kind="functionlike"><macro-parameter name="m"/><purpose>Documentation for macro example. </purpose></macro></header></library-reference>
+</programlisting></para><para>
+</para></description></struct><enum name="namespace_enum"><enumvalue name="enumerator"/></enum><data-member name="namespace_integer"><type>int</type></data-member><data-member name="namespace_static_integer" specifiers="static"><type>int</type></data-member><data-member name="namespace_const_integer"><type>const int</type></data-member><data-member name="namespace_static_const_integer" specifiers="static"><type>const int</type></data-member><function name="namespace_func"><type>int</type><parameter name="i"><paramtype>int</paramtype><description><para>A function parameter </para></description></parameter><parameter name="j"><paramtype>int</paramtype><description><para>Another </para></description></parameter><description><para>
+
+
+This is a test function. <classname alt="example::example">Link to class</classname> <classname alt="example::example_template">Link to class template</classname> <note><para>This is a note. </para></note>
+</para></description><requires><para>i &gt; j</para></requires><returns><para>The answer </para></returns></function></namespace><macro name="EXAMPLE" kind="functionlike"><macro-parameter name="m"/><purpose>Documentation for macro example. </purpose></macro></header></library-reference>

Modified: trunk/tools/boostbook/test/doxygen/boost/example.hpp
==============================================================================
--- trunk/tools/boostbook/test/doxygen/boost/example.hpp (original)
+++ trunk/tools/boostbook/test/doxygen/boost/example.hpp 2011-04-02 13:35:13 EDT (Sat, 02 Apr 2011)
@@ -89,11 +89,27 @@
      * 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.
+ */
+ int namespace_func(int i, int j);
 }
 
 #define EXAMPLE(m) The macro

Modified: trunk/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl
==============================================================================
--- trunk/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl (original)
+++ trunk/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl 2011-04-02 13:35:13 EDT (Sat, 02 Apr 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) &gt; 0">
- <notes>
- <xsl:apply-templates select="$notes" mode="function-clauses"/>
- </notes>
- </xsl:if>
   </xsl:template>
 
   <!-- Handle free functions -->
@@ -1259,6 +1281,12 @@
     </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"/>
@@ -1315,7 +1343,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 +1376,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 +1391,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: trunk/tools/boostbook/xsl/reference.xsl
==============================================================================
--- trunk/tools/boostbook/xsl/reference.xsl (original)
+++ trunk/tools/boostbook/xsl/reference.xsl 2011-04-02 13:35:13 EDT (Sat, 02 Apr 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: trunk/tools/boostbook/xsl/template.xsl
==============================================================================
--- trunk/tools/boostbook/xsl/template.xsl (original)
+++ trunk/tools/boostbook/xsl/template.xsl 2011-04-02 13:35:13 EDT (Sat, 02 Apr 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