From bfa67ad183425f467bc71a268c339b02faf5b0f3 Mon Sep 17 00:00:00 2001
From: Douglas Gregor <doug.gregor@gmail.com>
Date: Mon, 7 Jul 2003 15:31:34 +0000
Subject: [PATCH] dtd/boostbook.dtd: 	- Parameters can now have
 <description> elements 	- Add function specifiers

xsl/function.xsl:
	- When needed, place function return type on a separate line
	- Format <description> element for parameters
	- Use "spacing=boost" for variablelists used for function requirements

xsl/doxygen/doxygen2boostbook.xsl:
	- Emit <description> elements for parameters when available
	- Properly translate file descriptions


[SVN r18963]
---
 dtd/boostbook.dtd                 |   5 +-
 xsl/doxygen/doxygen2boostbook.xsl |  70 +++++++++++++++-
 xsl/function.xsl                  | 128 +++++++++++++++++++-----------
 3 files changed, 152 insertions(+), 51 deletions(-)

diff --git a/dtd/boostbook.dtd b/dtd/boostbook.dtd
index 240d996..1ed733f 100644
--- a/dtd/boostbook.dtd
+++ b/dtd/boostbook.dtd
@@ -211,7 +211,8 @@
 
 <!ELEMENT data-member (type, purpose?, description?)>
 <!ATTLIST data-member 
-    name   CDATA  #REQUIRED
+    name         CDATA  #REQUIRED
+    specifiers   CDATA  #IMPLIED
     %boost.common.attrib;>
 
 <!ELEMENT paramtype ANY>
@@ -370,7 +371,7 @@
 
 <!ELEMENT if-fails ANY>
 
-<!ELEMENT parameter (paramtype, default?)>
+<!ELEMENT parameter (paramtype, default?, description?)>
 <!ATTLIST parameter 
      name CDATA #IMPLIED>
 
diff --git a/xsl/doxygen/doxygen2boostbook.xsl b/xsl/doxygen/doxygen2boostbook.xsl
index 123bb56..2214d93 100644
--- a/xsl/doxygen/doxygen2boostbook.xsl
+++ b/xsl/doxygen/doxygen2boostbook.xsl
@@ -267,8 +267,10 @@ Cannot handle compounddef with kind=<xsl:value-of select="@kind"/>
                                        string(compoundname))"/>
         </xsl:attribute>
         
-        <xsl:apply-templates select="briefdescription" mode="passthrough"/>
-        <xsl:apply-templates select="detaileddescription" mode="passthrough"/>
+        <xsl:if test="briefdescription/*|detaileddescription/*">
+          <xsl:apply-templates select="briefdescription/*" mode="passthrough"/>
+          <xsl:apply-templates select="detaileddescription/*" mode="passthrough"/>
+        </xsl:if>
         
         <xsl:apply-templates mode="toplevel">
           <xsl:with-param name="with-namespace-refs"
@@ -455,6 +457,9 @@ Cannot handle compounddef with kind=<xsl:value-of select="@kind"/>
         </method-group>
         <xsl:apply-templates/>
       </xsl:when>
+      <xsl:when test="@kind='public-static-attrib' or @kind='public-attrib'">
+        <xsl:apply-templates/>
+      </xsl:when>
       <xsl:when test="@kind='public-type'">
         <xsl:apply-templates/>
       </xsl:when>
@@ -466,9 +471,15 @@ Cannot handle compounddef with kind=<xsl:value-of select="@kind"/>
       <xsl:when test="@kind='typedef'">
         <xsl:apply-templates/>
       </xsl:when>
+      <xsl:when test="@kind='var'">
+        <xsl:apply-templates/>
+      </xsl:when>
       <xsl:when test="@kind='enum'">
         <xsl:apply-templates/>
       </xsl:when>
+      <xsl:when test="@kind='user-defined'">
+        <xsl:apply-templates/>
+      </xsl:when>
       <xsl:otherwise>
         <xsl:message>
 Cannot handle sectiondef with kind=<xsl:value-of select="@kind"/>      
@@ -532,6 +543,9 @@ Cannot handle sectiondef with kind=<xsl:value-of select="@kind"/>
       <xsl:when test="@kind='enum'">
         <xsl:call-template name="enum"/>
       </xsl:when>
+      <xsl:when test="@kind='variable'">
+        <xsl:call-template name="variable"/>
+      </xsl:when>
       <xsl:otherwise>
         <xsl:message>
 Cannot handle memberdef element with kind=<xsl:value-of select="@kind"/>
@@ -572,16 +586,42 @@ Cannot handle memberdef element with kind=<xsl:value-of select="@kind"/>
         <xsl:apply-templates select="type/*|type/text()" mode="passthrough"/>
       </paramtype>
 
-      <!-- TBD: handling of parameter descriptions -->
+      <!-- Default argument -->
       <xsl:if test="defval">
         <default>
           <xsl:apply-templates select="defval/*|defval/text()" 
             mode="passthrough"/>
         </default>
       </xsl:if>
+
+      <!-- Parameter description -->
+      <xsl:variable name="name">
+        <xsl:value-of select="declname/text()"/>
+      </xsl:variable>
+
+      <xsl:apply-templates select="../detaileddescription/para/parameterlist[attribute::kind='param']/parameterdescription"
+        mode="parameter.description">
+        <xsl:with-param name="name">
+          <xsl:value-of select="$name"/>
+        </xsl:with-param>
+      </xsl:apply-templates>
     </parameter>
   </xsl:template>
 
+  <xsl:template match="parameterdescription" mode="parameter.description">
+    <!-- The parameter name we are looking for -->
+    <xsl:param name="name"/>
+
+    <!-- The parametername node associated with this description -->
+    <xsl:variable name="name-node" select="../*[position()=1]"/>
+
+    <xsl:if test="string($name-node/text()) = $name">
+      <description>
+        <xsl:apply-templates select="para" mode="passthrough"/>
+      </description>
+    </xsl:if>
+  </xsl:template>
+
   <!-- Handle function children -->
   <xsl:template name="function.children">
     <!-- Emit template header -->
@@ -683,6 +723,30 @@ Cannot handle memberdef element with kind=<xsl:value-of select="@kind"/>
     </method>
   </xsl:template>
 
+  <!-- Handle member variables -->
+  <xsl:template name="variable">
+    <data-member>
+      <xsl:attribute name="name">
+        <xsl:value-of select="name/text()"/>
+      </xsl:attribute>
+
+      <!-- Specifiers -->
+      <xsl:if test="@static = 'yes'">
+        <xsl:attribute name="specifiers">static</xsl:attribute>
+      </xsl:if>
+      <xsl:if test="@mutable = 'yes'">
+        <xsl:attribute name="specifiers">mutable</xsl:attribute>
+      </xsl:if>
+
+      <type>
+        <xsl:apply-templates select="type/text()|type/*" mode="passthrough"/>
+      </type>
+
+      <xsl:apply-templates select="briefdescription" mode="passthrough"/>
+      <xsl:apply-templates select="detaileddescription" mode="passthrough"/>
+    </data-member>
+  </xsl:template>
+
   <!-- Things we ignore directly -->
   <xsl:template match="compoundname" mode="toplevel"/>
   <xsl:template match="includes|includedby|incdepgraph|invincdepgraph" mode="toplevel"/>
diff --git a/xsl/function.xsl b/xsl/function.xsl
index d331d4a..dd7bdcb 100644
--- a/xsl/function.xsl
+++ b/xsl/function.xsl
@@ -14,6 +14,13 @@
        "standardese", for now -->
   <xsl:param name="boost.generation.mode">compact</xsl:param>
 
+  <!-- The longest type length that is considered "short" for the
+       layout of function return types. When the length of the result type
+       and any storage specifiers is greater than this length, they will be
+       placed on a separate line from the function name and parameters
+       unless everything fits on a single line. -->
+  <xsl:param name="boost.short.result.type">6</xsl:param>
+
   <!-- Display a function declaration -->
   <xsl:template name="function">
     <xsl:param name="indentation"/>
@@ -56,6 +63,9 @@
     <!-- True if this is the function's separate documentation -->
     <xsl:param name="standalone" select="false()"/>
 
+    <!-- True if we should suppress the template header -->
+    <xsl:param name="suppress-template" select="false()"/>
+
     <!-- Calculate the type -->
     <xsl:variable name="type">
       <xsl:if test="@specifiers">
@@ -109,7 +119,8 @@
     </xsl:variable>
 
     <xsl:if test="not ($standalone) or 
-                  (local-name(.)='signature' and (position() &gt; 1))">
+                  (local-name(.)='signature' and (position() &gt; 1))
+                  or $suppress-template">
       <xsl:text>&#10;</xsl:text>
     </xsl:if>
 
@@ -120,7 +131,14 @@
     
     <!-- Build the template header -->
     <xsl:variable name="template-length">
-      <xsl:call-template name="template.synopsis.length"/>
+      <xsl:choose>
+        <xsl:when test="$suppress-template">
+          0
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:call-template name="template.synopsis.length"/>
+        </xsl:otherwise>
+      </xsl:choose>
     </xsl:variable>
         
     <!-- Build a full parameter string (without line breaks) -->
@@ -156,40 +174,21 @@
         <xsl:apply-templates select="template" mode="synopsis">
           <xsl:with-param name="indentation" select="$indentation"/>
         </xsl:apply-templates>
-        <xsl:text>&#10;</xsl:text>
-        <xsl:call-template name="indent">
-          <xsl:with-param name="indentation" select="$indentation + 2"/>
-        </xsl:call-template>
         
-        <!-- Emit the function declaration without parameters -->
-        <xsl:call-template name="source-highlight">
-          <xsl:with-param name="text" select="$type"/>
-        </xsl:call-template>
-        <xsl:call-template name="link-or-anchor">
-          <xsl:with-param name="to" select="$link-to"/>
-          <xsl:with-param name="text">
-             <xsl:call-template name="source-highlight">
-                <xsl:with-param name="text" 
-                  select="$function-name"/>
-              </xsl:call-template>            
-          </xsl:with-param>
-          <xsl:with-param name="link-type" select="$link-type"/>
-          <xsl:with-param name="highlight" select="true()"/>
-        </xsl:call-template>
-
-        <!-- Emit the parameters -->
-        <xsl:text>(</xsl:text>
-        <xsl:call-template name="function-parameters">
+        <!-- Emit the rest of the function declaration (without the
+             template header) indented two extra spaces. -->
+        <xsl:call-template name="function">
+          <xsl:with-param name="indentation" select="$indentation + 2"/>
+          <xsl:with-param name="is-reference" select="$is-reference"/>
           <xsl:with-param name="include-names" select="$include-names"/>
-          <xsl:with-param name="indentation" 
-            select="$indentation + 3 + string-length($type) +
-                    string-length($function-name)"/>
-          <xsl:with-param name="final" select="true()"/>
-        </xsl:call-template>
-        <xsl:text>)</xsl:text>
-
-        <xsl:call-template name="source-highlight">
-          <xsl:with-param name="text" select="$postdeclarator"/>
+          <xsl:with-param name="link-type" select="$link-type"/>
+          <xsl:with-param name="link-to" select="$link-to"/>
+          <xsl:with-param name="constructor-for" select="$constructor-for"/>
+          <xsl:with-param name="destructor-for" select="$destructor-for"/>
+          <xsl:with-param name="copy-assign-for" select="$copy-assign-for"/>
+          <xsl:with-param name="name" select="$name"/>
+          <xsl:with-param name="standalone" select="$standalone"/>
+          <xsl:with-param name="suppress-template" select="true()"/>
         </xsl:call-template>
       </xsl:when>
 
@@ -198,11 +197,13 @@
         <xsl:call-template name="link-or-anchor">
           <xsl:with-param name="to" select="$link-to"/>
           <xsl:with-param name="text">
-            <xsl:apply-templates select="template" mode="synopsis">
-              <xsl:with-param name="indentation" select="$indentation"/>
-              <xsl:with-param name="wrap" select="false()"/>
-              <xsl:with-param name="highlight" select="false()"/>
-            </xsl:apply-templates>
+            <xsl:if test="not($suppress-template)">
+              <xsl:apply-templates select="template" mode="synopsis">
+                <xsl:with-param name="indentation" select="$indentation"/>
+                <xsl:with-param name="wrap" select="false()"/>
+                <xsl:with-param name="highlight" select="false()"/>
+              </xsl:apply-templates>
+            </xsl:if>
             <xsl:value-of select="$type"/>
             <xsl:value-of select="$function-name"/>
             <xsl:text>(</xsl:text>
@@ -218,17 +219,35 @@
           </xsl:with-param>
           <xsl:with-param name="link-type" select="$link-type"/>
           <xsl:with-param name="highlight" select="true()"/>
-        </xsl:call-template>        
+        </xsl:call-template>
+        <xsl:text>;</xsl:text>    
       </xsl:when>
 
       <!-- This declaration will take multiple lines -->
       <xsl:otherwise>
-        <xsl:apply-templates select="template" mode="synopsis">
-          <xsl:with-param name="indentation" select="$indentation"/>
-        </xsl:apply-templates>
         <xsl:call-template name="source-highlight">
           <xsl:with-param name="text" select="$type"/>
         </xsl:call-template>
+        <xsl:if test="string-length($type) &gt; $boost.short.result.type">
+          <xsl:text>&#10;</xsl:text>
+          <xsl:call-template name="indent">
+            <xsl:with-param name="indentation" select="$indentation"/>
+          </xsl:call-template>
+        </xsl:if>
+
+        <!-- Determine how many columns the type and storage
+             specifiers take on the same line as the function name. -->
+        <xsl:variable name="type-length">
+          <xsl:choose>
+            <xsl:when test="string-length($type) &gt; $boost.short.result.type">
+              0
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:value-of select="string-length($type)"/>
+            </xsl:otherwise>
+          </xsl:choose>
+        </xsl:variable>
+
         <xsl:call-template name="link-or-anchor">
           <xsl:with-param name="to" select="$link-to"/>
           <xsl:with-param name="text" select="$function-name"/>
@@ -239,7 +258,7 @@
         <xsl:call-template name="function-parameters">
           <xsl:with-param name="include-names" select="$include-names"/>
           <xsl:with-param name="indentation" 
-            select="$indentation + $template-length + string-length($type)
+            select="$indentation + $type-length 
                     + string-length($function-name) + 1"/>
           <xsl:with-param name="final" select="true()"/>
         </xsl:call-template>                
@@ -247,9 +266,9 @@
         <xsl:call-template name="source-highlight">
           <xsl:with-param name="text" select="$postdeclarator"/>
         </xsl:call-template>
+        <xsl:text>;</xsl:text>
       </xsl:otherwise>
     </xsl:choose>
-    <xsl:text>;</xsl:text>
   </xsl:template>    
 
   <!-- Synopsis of function parameters, e.g., "(const T&, int x = 5)" -->
@@ -660,6 +679,23 @@
       <xsl:apply-templates select="purpose/*"/>
     </xsl:if>
 
+    <!-- Document parameters -->
+    <xsl:if test="parameter/description">
+      <variablelist spacing="compact">
+        <title>Parameters</title>
+        <xsl:for-each select="parameter">
+          <xsl:if test="description">
+            <varlistentry>
+              <term><xsl:value-of select="@name"/></term>
+              <listitem>
+                <xsl:apply-templates select="description/*"/>
+              </listitem>
+            </varlistentry>
+          </xsl:if>
+        </xsl:for-each>
+      </variablelist>
+    </xsl:if>
+
     <xsl:apply-templates select="description/*"/>
 
     <xsl:if test="para">
@@ -715,7 +751,7 @@
 
   <!-- The "compact" function requirements mode uses variable lists -->
   <xsl:template name="function.requirements.compact">
-    <variablelist>
+    <variablelist spacing="boost">
       <xsl:apply-templates 
         select="requires|effects|postconditions|returns|throws|complexity|
                 notes|rationale"