Re: [Boost-docs] [boostbook][patch] typedef class member descriptions

Subject: Re: [Boost-docs] [boostbook][patch] typedef class member descriptions
From: Frank Mori Hess (frank.hess_at_[hidden])
Date: 2007-10-29 18:16:52

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Monday 29 October 2007 12:00 pm, Frank Mori Hess wrote:
> Attached is a patch against trunk for review/comment which adds
> descriptions of class member typedefs to class documentation.  This
> replaces Daniel James' previous one-line patch:
>
> http://svn.boost.org/trac/boost/changeset/39711
>
> which I accidentally wiped out from the trunk when merging my previous
> patches for the <access> element.  Unfortunately, I have to admit this
> resulted in me never actually seeing exactly what the output of his
> one-line solution looked like, so I'm only assuming my patch produces nicer
> output (it's bigger so it's gotta be better, right?)

Oops, here's a better patch.  The first one left out changeset 39391 from the 
boost_docs sandbox:

http://svn.boost.org/trac/boost/changeset/39391

which prevents the generation of broken links in certain cases.

- -- 
Frank
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)

iD8DBQFHJiOW5vihyNWuA4URAtqdAKCcjJw2t6qWFxE6LzFX5gGFrPCfvACeLQAi
We5nLJEQXwQeLQk9MkOfp+o=
=itir
-----END PGP SIGNATURE-----

--Boundary-00=_WOiJHgUmvDG/vMo
Content-Type: text/x-diff; charset="utf-8";
        name="boostbook_typedef_descriptions2.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
        filename="boostbook_typedef_descriptions2.patch"

Index: tools/boostbook/xsl/type.xsl
===================================================================
--- tools/boostbook/xsl/type.xsl	(revision 40555)
+++ tools/boostbook/xsl/type.xsl	(working copy)
@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!--
    Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com>
+   Copyright (c) 2007 Frank Mori Hess <fmhess_at_[hidden]>
 
    Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at
@@ -379,7 +380,7 @@
   </xsl:template>
 
   <!-- Emit a typedef reference entry -->
-  <xsl:template match="typedef" mode="reference">
+  <xsl:template match="typedef" mode="namespace-reference">
     <!-- True if this typedef was compacted -->
     <xsl:variable name="compact"
       select="not (para|description) and ($boost.compact.typedef='1')"/>
@@ -412,6 +413,28 @@
     </xsl:if>
   </xsl:template>
 
+  <xsl:template match="typedef" mode="reference">
+    <!-- True if this typedef was compacted -->
+    <xsl:variable name="compact"
+      select="not (para|description) and ($boost.compact.typedef='1')"/>
+
+    <xsl:if test="not ($compact)">
+      <listitem>
+        <para>
+          <xsl:call-template name="type.typedef.display.aligned">
+            <xsl:with-param name="compact" select="false()"/>
+            <xsl:with-param name="indentation" select="0"/>
+            <xsl:with-param name="is-reference" select="true()"/>
+            <xsl:with-param name="link-type" select="'anchor'"/>
+          </xsl:call-template>
+        </para>
+        <para>
+          <xsl:apply-templates select="description"/>
+        </para>
+      </listitem>
+    </xsl:if>
+  </xsl:template>
+
   <!-- Emit a list of static constants -->
   <xsl:template match="static-constant" mode="synopsis">
     <xsl:param name="indentation"/>
@@ -698,9 +721,26 @@
       <xsl:call-template name="indent">
         <xsl:with-param name="indentation" select="$indentation + 2"/>
       </xsl:call-template>
-      <xsl:call-template name="highlight-comment">
-        <xsl:with-param name="text" select="'// types'"/>
-      </xsl:call-template>
+      <emphasis>
+        <xsl:text>// </xsl:text>
+        <!-- True if there are any non-compacted typedefs -->
+        <xsl:variable name="have-typedef-references"
+          select="typedef and ((typedef/para|typedef/description) or ($boost.compact.typedef='0'))"/>
+        <xsl:choose>
+          <xsl:when test="$have-typedef-references">
+            <xsl:call-template name="internal-link">
+              <xsl:with-param name="to">
+                <xsl:call-template name="generate.id"/>
+                <xsl:text>types</xsl:text>
+              </xsl:with-param>
+              <xsl:with-param name="text" select="'types'"/>
+            </xsl:call-template>
+          </xsl:when>
+          <xsl:otherwise>
+            <xsl:text>types</xsl:text>
+          </xsl:otherwise>
+        </xsl:choose>
+      </emphasis>
 
       <xsl:variable name="max-type-length">
         <xsl:call-template name="find-max-type-length"/>
@@ -900,7 +940,42 @@
     </xsl:call-template>
   </xsl:template>
 
+  <xsl:template name="member-typedefs-reference">
+    <!-- True if there are any non-compacted typedefs -->
+    <xsl:variable name="have-typedef-references"
+      select="typedef and ((typedef/para|typedef/description) or ($boost.compact.typedef='0'))"/>
+    <xsl:if test="$have-typedef-references">
+      <xsl:call-template name="member-documentation">
+        <xsl:with-param name="name">
+          <xsl:call-template name="anchor">
+            <xsl:with-param name="to">
+              <xsl:call-template name="generate.id"/>
+              <xsl:text>types</xsl:text>
+            </xsl:with-param>
+            <xsl:with-param name="text" select="''"/>
+          </xsl:call-template>
+          <xsl:call-template name="monospaced">
+            <xsl:with-param name="text">
+              <xsl:call-template name="object-name"/>
+            </xsl:with-param>
+          </xsl:call-template>
+          <xsl:text> </xsl:text>
+          <xsl:call-template name="access-name"/>
+          <xsl:text> types</xsl:text>
+        </xsl:with-param>
+        <xsl:with-param name="text">
+          <orderedlist>
+            <xsl:apply-templates select="typedef" mode="reference"/>
+          </orderedlist>
+        </xsl:with-param>
+      </xsl:call-template>
+    </xsl:if>
+ </xsl:template>
+
   <xsl:template name="class-members-reference">
+
+    <xsl:call-template name="member-typedefs-reference"/>
+
     <xsl:call-template name="construct-copy-destruct-reference"/>
 
     <xsl:apply-templates
Index: tools/boostbook/xsl/reference.xsl
===================================================================
--- tools/boostbook/xsl/reference.xsl	(revision 40555)
+++ tools/boostbook/xsl/reference.xsl	(working copy)
@@ -82,14 +82,14 @@
 
   <!-- Emit namespace reference -->
   <xsl:template match="namespace" mode="reference">
-    <xsl:apply-templates select="namespace|typedef|free-function-group"
+    <xsl:apply-templates select="namespace|free-function-group"
       mode="reference">
       <xsl:with-param name="indentation" select="0"/>
     </xsl:apply-templates>
     <xsl:apply-templates select="class|class-specialization|
                                  struct|struct-specialization|
                                  union|union-specialization|enum|function|
-                                 overloaded-function|data-member"
+                                 overloaded-function|data-member|typedef"
       mode="namespace-reference"/>
   </xsl:template>
 

--Boundary-00=_WOiJHgUmvDG/vMo--