From 2f93254d2c929d0563c2ab8152da62ee0a91ea10 Mon Sep 17 00:00:00 2001
From: Hans Bolinder <hasse@erlang.org>
Date: Thu, 8 Jul 2010 13:20:32 +0200
Subject: Prepare erl_docgen for using Dialyzer specs and types

Support for using Dialyzer specifications and types has been added.
This is an experimental release; changes are expected before the new
functionality is used when building the OTP documentation.
---
 lib/erl_docgen/priv/xsl/db_man.xsl | 338 +++++++++++++++++++++++++++++++++----
 1 file changed, 307 insertions(+), 31 deletions(-)

(limited to 'lib/erl_docgen/priv/xsl/db_man.xsl')

diff --git a/lib/erl_docgen/priv/xsl/db_man.xsl b/lib/erl_docgen/priv/xsl/db_man.xsl
index 71c4a66707..2ed0d95c6d 100644
--- a/lib/erl_docgen/priv/xsl/db_man.xsl
+++ b/lib/erl_docgen/priv/xsl/db_man.xsl
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!--      
+<!--
      #
      # %CopyrightBegin%
      #
@@ -17,24 +17,294 @@
      # under the License.
      #
      # %CopyrightEnd%
-     
+
      -->
 
 <xsl:stylesheet version="1.0"
-  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> 
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 
   <xsl:preserve-space elements="code pre"/>
   <xsl:strip-space elements="*"/>
   <xsl:output method="text" encoding="UTF-8" indent="no"/>
 
+  <!-- Start of Dialyzer type/spec tags. See also the template matching "name"
+  -->
+
+  <!-- Note: specs data for *one* module (as opposed to html and pdf) -->
+  <xsl:param name="specs_file" select="''"/>
+  <xsl:variable name="i" select="document($specs_file)"></xsl:variable>
+
+  <xsl:template name="err">
+    <xsl:param name="m"/>
+    <xsl:param name="n"/>
+    <xsl:param name="a"/>
+    <xsl:param name="s"/>
+    <xsl:message terminate="yes">
+  Error <xsl:if test="$m != ''"><xsl:value-of select ="$m"/>:</xsl:if>
+	 <xsl:value-of
+		   select="$n"/>/<xsl:value-of
+		   select="$a"/>: <xsl:value-of select="$s"/>
+    </xsl:message>
+  </xsl:template>
+
+  <xsl:template name="spec_name">
+    <xsl:variable name="curModule" select="ancestor::erlref/module"/>
+    <xsl:variable name="mod" select="@mod"/>
+    <xsl:variable name="name" select="@name"/>
+    <xsl:variable name="arity" select="@arity"/>
+    <xsl:variable name="clause" select="@clause"/>
+    <xsl:variable name="spec0" select=
+        "$i/module[@name=$curModule]/spec
+             [name=$name and arity=$arity
+              and (string-length($mod) = 0 or module = $mod)]"/>
+    <xsl:variable name="spec" select="$spec0[string-length($clause) = 0
+                                             or position() = $clause]"/>
+    <xsl:if test="count($spec) = 0">
+      <xsl:call-template name="err">
+	<xsl:with-param name="m" select="$mod"/>
+	<xsl:with-param name="n" select="$name"/>
+	<xsl:with-param name="a" select="$arity"/>
+	<xsl:with-param name="s">unknown spec</xsl:with-param>
+      </xsl:call-template>
+    </xsl:if>
+
+    <xsl:choose>
+      <xsl:when test="ancestor::cref">
+	<xsl:message terminate="yes">
+          Error: did not expect a 'name' tag with name/arity attributes here!
+	</xsl:message>
+      </xsl:when>
+      <xsl:when test="ancestor::erlref">
+	<xsl:choose>
+	  <xsl:when test="string(@with_guards) = 'no'">
+	     <xsl:apply-templates select="$spec/contract/clause/head"/>
+	  </xsl:when>
+	  <xsl:otherwise>
+            <xsl:call-template name="contract">
+              <xsl:with-param name="contract" select="$spec/contract"/>
+            </xsl:call-template>
+	  </xsl:otherwise>
+	</xsl:choose>
+        <xsl:text>&#10;.br</xsl:text>
+      </xsl:when>
+    </xsl:choose>
+  </xsl:template>
+
+  <xsl:template name="contract">
+    <xsl:param name="contract"/>
+    <xsl:call-template name="clause">
+      <xsl:with-param name="clause" select="$contract/clause"/>
+    </xsl:call-template>
+  </xsl:template>
+
+  <xsl:template name="clause">
+    <xsl:param name="clause"/>
+    <xsl:variable name="type_desc" select="../type_desc"/>
+    <xsl:for-each select="$clause">
+      <xsl:apply-templates select="head"/>
+      <xsl:if test="count(guard) > 0">
+	<xsl:call-template name="guard">
+	  <xsl:with-param name="guard" select="guard"/>
+	  <xsl:with-param name="type_desc" select="$type_desc"/>
+	</xsl:call-template>
+      </xsl:if>
+    </xsl:for-each>
+  </xsl:template>
+
+  <xsl:template match="head">
+    <xsl:text>&#10;.nf&#10;</xsl:text>
+    <xsl:text>&#10;.B&#10;</xsl:text>
+    <xsl:apply-templates/>
+    <xsl:text>&#10;.br</xsl:text>
+    <xsl:text>&#10;.fi</xsl:text>
+  </xsl:template>
+
+  <xsl:template name="guard">
+    <xsl:param name="guard"/>
+    <xsl:param name="type_desc"/>
+    <xsl:text>&#10;.RS</xsl:text>
+    <xsl:text>&#10;.TP</xsl:text>
+    <xsl:text>&#10;Types</xsl:text>
+    <xsl:call-template name="subtype">
+      <xsl:with-param name="subtype" select="$guard/subtype"/>
+      <xsl:with-param name="type_desc" select="$type_desc"/>
+    </xsl:call-template>
+    <xsl:text>&#10;.RE</xsl:text>
+  </xsl:template>
+
+  <xsl:template name="subtype">
+    <xsl:param name="subtype"/>
+    <xsl:param name="type_desc"/>
+    <xsl:for-each select="$subtype">
+      <xsl:variable name="tname" select="typename"/>
+      <xsl:variable name="tdesc" select="$type_desc[@name = $tname]"/>
+        <xsl:text>&#10;</xsl:text>
+        <xsl:apply-templates select="string"/>
+        <xsl:text>&#10;.br</xsl:text>
+      <xsl:apply-templates select="$type_desc[@name = $tname]"/>
+    </xsl:for-each>
+  </xsl:template>
+
+  <!-- Note: <type_desc> has not been implemented for data types. -->
+
+  <!-- Similar to <d> -->
+  <xsl:template match="type_desc">
+    <xsl:text>&#10;</xsl:text><xsl:apply-templates/>
+    <xsl:text>&#10;.br</xsl:text>
+  </xsl:template>
+
+  <!-- Datatypes -->
+  <xsl:template match="datatypes">
+    <xsl:text>&#10;.SH DATA TYPES</xsl:text>
+    <xsl:apply-templates/>
+  </xsl:template>
+
+  <!-- Datatype -->
+  <xsl:template match="datatype">
+    <xsl:apply-templates/>
+  </xsl:template>
+
+  <xsl:template match="typehead">
+    <xsl:text>&#10;.nf&#10;</xsl:text>
+    <xsl:text>&#10;.B&#10;</xsl:text>
+    <xsl:apply-templates/>
+    <xsl:text>&#10;.br</xsl:text>
+    <xsl:text>&#10;.fi</xsl:text>
+  </xsl:template>
+
+  <xsl:template match="local_defs">
+    <xsl:text>&#10;.RS</xsl:text>
+    <xsl:apply-templates/>
+    <xsl:text>&#10;.RE</xsl:text>
+  </xsl:template>
+
+  <xsl:template match="local_def">
+    <xsl:text>&#10;</xsl:text>
+    <xsl:apply-templates/>
+    <xsl:text>&#10;.br</xsl:text>
+  </xsl:template>
+
+  <xsl:template name="type_name">
+    <xsl:variable name="curModule" select="ancestor::erlref/module"/>
+    <xsl:variable name="mod" select="@mod"/>
+    <xsl:variable name="name" select="@name"/>
+    <xsl:variable name="n_vars">
+      <xsl:choose>
+	<xsl:when test="string-length(@n_vars) > 0">
+	  <xsl:value-of select="@n_vars"/>
+	</xsl:when>
+	<xsl:otherwise>
+          <xsl:value-of select="0"/>
+	</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+
+    <xsl:choose>
+      <xsl:when test="string-length($name) > 0">
+	<xsl:variable name="type" select=
+	    "$i/module[@name=$curModule]/type
+		 [name=$name and n_vars=$n_vars
+		  and (string-length($mod) = 0 or module = $mod)]"/>
+
+	<xsl:if test="count($type) != 1">
+	  <xsl:call-template name="err">
+	    <xsl:with-param name="m" select="$mod"/>
+	    <xsl:with-param name="n" select="$name"/>
+	    <xsl:with-param name="a" select="$n_vars"/>
+	    <xsl:with-param name="s">unknown type</xsl:with-param>
+	  </xsl:call-template>
+	</xsl:if>
+	<xsl:apply-templates select="$type/typedecl"/>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:text>&#10;.nf&#10;</xsl:text>
+        <xsl:text>&#10;.B&#10;</xsl:text>
+        <xsl:apply-templates/>
+        <xsl:text>&#10;.br</xsl:text>
+        <xsl:text>&#10;.fi</xsl:text>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
+  <!-- Used both in <datatype> and in <func>! -->
+  <xsl:template match="anno">
+    <xsl:variable name="curModule" select="ancestor::erlref/module"/>
+    <xsl:variable name="anno" select="normalize-space(text())"/>
+    <xsl:variable name="namespec"
+                  select="ancestor::desc/preceding-sibling::name"/>
+    <xsl:if test="count($namespec) = 0 and string-length($specs_file) > 0">
+      <xsl:call-template name="err">
+	<xsl:with-param name="s">cannot find 'name' (<xsl:value-of select="$anno"/>)
+	</xsl:with-param>
+      </xsl:call-template>
+    </xsl:if>
+
+    <xsl:variable name="mod" select="$namespec/@mod"/>
+    <xsl:variable name="name" select="$namespec/@name"/>
+    <xsl:variable name="arity" select="$namespec/@arity"/>
+    <xsl:variable name="clause" select="$namespec/@clause"/>
+    <xsl:variable name="tmp_n_vars" select="$namespec/@n_vars"/>
+    <xsl:variable name="n_vars">
+      <xsl:choose>
+	<xsl:when test="string-length($tmp_n_vars) > 0">
+	  <xsl:value-of select="$tmp_n_vars"/>
+	</xsl:when>
+	<xsl:otherwise>
+          <xsl:value-of select="0"/>
+	</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:variable name="spec0" select=
+        "$i/module[@name=$curModule]/spec
+             [name=$name and arity=$arity
+              and (string-length($mod) = 0 or module = $mod)]"/>
+    <xsl:variable name="spec_annos" select=
+         "$spec0[string-length($clause) = 0
+                 or position() = $clause]/anno[.=$anno]"/>
+    <xsl:variable name="type_annos" select=
+        "$i/module[@name=$curModule]/type
+             [name=$name and n_vars=$n_vars
+              and (string-length($mod) = 0 or module = $mod)]/anno[.=$anno]"/>
+
+    <xsl:if test="count($spec_annos) = 0
+                  and count($type_annos) = 0
+	          and string-length($specs_file) > 0">
+      <xsl:variable name="n">
+        <xsl:choose>
+          <xsl:when test="string-length($arity) = 0">
+            <xsl:value-of select="$n_vars"/>
+          </xsl:when>
+          <xsl:otherwise>
+            <xsl:value-of select="$arity"/>
+          </xsl:otherwise>
+        </xsl:choose>
+      </xsl:variable>
+      <xsl:call-template name="err">
+	<xsl:with-param name="m" select="$mod"/>
+	<xsl:with-param name="n" select="$name"/>
+	<xsl:with-param name="a" select="$n"/>
+	<xsl:with-param name="s">unknown annotation <xsl:value-of select="$anno"/>
+	</xsl:with-param>
+      </xsl:call-template>
+    </xsl:if>
+    <xsl:value-of select="$anno"/>
+  </xsl:template>
+
+  <!-- Used for indentation of formatted types and specs -->
+  <xsl:template match="nbsp">
+    <xsl:text> </xsl:text>
+  </xsl:template>
+
+  <!-- End of Dialyzer type/spec tags -->
+
   <!-- Header -->
   <xsl:template match="header">
   </xsl:template>
-  
+
   <!-- Section/Title -->
   <xsl:template match="section/title">
   </xsl:template>
-  
+
   <!-- *ref/Section -->
   <xsl:template match="erlref/section|comref/section|cref/section|fileref/section|appref/section">
     <xsl:text>&#10;.SH "</xsl:text><xsl:value-of select="translate(title, 'abcdefghijklmnopqrstuvwxyz','ABCDEFGHIJKLMNOPQRSTUVWXYZ')"/><xsl:text>"&#10;</xsl:text>
@@ -49,7 +319,7 @@
 
 
   <!-- Lists -->
-  
+
   <xsl:template match="list">
     <xsl:text>&#10;.RS 2</xsl:text>
     <xsl:apply-templates/>
@@ -68,7 +338,7 @@
     <xsl:apply-templates select="tag|item"/>
     <xsl:text>&#10;.RE</xsl:text>
   </xsl:template>
-  
+
   <xsl:template match="taglist/tag">
     <xsl:text>&#10;.TP 2&#10;</xsl:text>
     <xsl:text>.B&#10;</xsl:text>
@@ -76,7 +346,7 @@
   </xsl:template>
 
   <xsl:template match="taglist/item">
-    <xsl:apply-templates/>        
+    <xsl:apply-templates/>
   </xsl:template>
 
   <xsl:template match="item/p">
@@ -88,10 +358,10 @@
         <xsl:value-of select="$content"/>
       </xsl:when>
       <xsl:otherwise>
-        <xsl:text>&#10;.RS 2</xsl:text>     
-        <xsl:text>&#10;.LP&#10;&#10;.LP&#10;</xsl:text>     
+        <xsl:text>&#10;.RS 2</xsl:text>
+        <xsl:text>&#10;.LP&#10;&#10;.LP&#10;</xsl:text>
         <xsl:value-of select="$content"/>
-        <xsl:text>&#10;.RE</xsl:text>     
+        <xsl:text>&#10;.RE</xsl:text>
       </xsl:otherwise>
     </xsl:choose>
   </xsl:template>
@@ -171,7 +441,7 @@
   <xsl:template match="application">
       <xsl:apply-templates/>
   </xsl:template>
-  
+
   <!-- Erlref -->
   <xsl:template match="/erlref">
     <xsl:variable name="companyname">
@@ -184,7 +454,7 @@
 
     <xsl:text>.TH </xsl:text><xsl:value-of select="module"/><xsl:text> 3 "</xsl:text><xsl:value-of select="$appname"/><xsl:text> </xsl:text><xsl:value-of select="$appver"/><xsl:text>" "</xsl:text><xsl:value-of select="$companyname"/><xsl:text>" "Erlang Module Definition"&#10;</xsl:text>
     <xsl:text>.SH NAME&#10;</xsl:text>
-    <xsl:value-of select="module"/><xsl:text> \- </xsl:text><xsl:value-of select="modulesummary"/><xsl:text>&#10;</xsl:text>  
+    <xsl:value-of select="module"/><xsl:text> \- </xsl:text><xsl:value-of select="modulesummary"/><xsl:text>&#10;</xsl:text>
     <xsl:apply-templates/>
   </xsl:template>
 
@@ -199,7 +469,7 @@
     </xsl:variable>
    <xsl:text>.TH </xsl:text><xsl:value-of select="com"/><xsl:text> 1 "</xsl:text><xsl:value-of select="$appname"/><xsl:text> </xsl:text><xsl:value-of select="$appver"/><xsl:text>" "</xsl:text><xsl:value-of select="$companyname"/><xsl:text>" "User Commands"&#10;</xsl:text>
     <xsl:text>.SH NAME&#10;</xsl:text>
-    <xsl:value-of select="com"/><xsl:text> \- </xsl:text><xsl:value-of select="comsummary"/><xsl:text>&#10;</xsl:text>  
+    <xsl:value-of select="com"/><xsl:text> \- </xsl:text><xsl:value-of select="comsummary"/><xsl:text>&#10;</xsl:text>
     <xsl:apply-templates/>
   </xsl:template>
 
@@ -214,7 +484,7 @@
     </xsl:variable>
     <xsl:text>.TH </xsl:text><xsl:value-of select="lib"/><xsl:text> 3 "</xsl:text><xsl:value-of select="$appname"/><xsl:text> </xsl:text><xsl:value-of select="$appver"/><xsl:text>" "</xsl:text><xsl:value-of select="$companyname"/><xsl:text>" "C Library Functions"&#10;</xsl:text>
     <xsl:text>.SH NAME&#10;</xsl:text>
-    <xsl:value-of select="lib"/><xsl:text> \- </xsl:text><xsl:value-of select="libsummary"/><xsl:text>&#10;</xsl:text>  
+    <xsl:value-of select="lib"/><xsl:text> \- </xsl:text><xsl:value-of select="libsummary"/><xsl:text>&#10;</xsl:text>
     <xsl:apply-templates/>
   </xsl:template>
 
@@ -229,7 +499,7 @@
     </xsl:variable>
     <xsl:text>.TH </xsl:text><xsl:value-of select="file"/><xsl:text> 5 "</xsl:text><xsl:value-of select="$appname"/><xsl:text> </xsl:text><xsl:value-of select="$appver"/><xsl:text>" "</xsl:text><xsl:value-of select="$companyname"/><xsl:text>" "Files"&#10;</xsl:text>
     <xsl:text>.SH NAME&#10;</xsl:text>
-    <xsl:value-of select="file"/><xsl:text> \- </xsl:text><xsl:value-of select="filesummary"/><xsl:text>&#10;</xsl:text>  
+    <xsl:value-of select="file"/><xsl:text> \- </xsl:text><xsl:value-of select="filesummary"/><xsl:text>&#10;</xsl:text>
     <xsl:apply-templates/>
   </xsl:template>
 
@@ -244,7 +514,7 @@
     </xsl:variable>
     <xsl:text>.TH </xsl:text><xsl:value-of select="app"/><xsl:text> 7 "</xsl:text><xsl:value-of select="$appname"/><xsl:text> </xsl:text><xsl:value-of select="$appver"/><xsl:text>" "</xsl:text><xsl:value-of select="$companyname"/><xsl:text>" "Erlang Application Definition"&#10;</xsl:text>
     <xsl:text>.SH NAME&#10;</xsl:text>
-    <xsl:value-of select="app"/><xsl:text> \- </xsl:text><xsl:value-of select="appsummary"/><xsl:text>&#10;</xsl:text>  
+    <xsl:value-of select="app"/><xsl:text> \- </xsl:text><xsl:value-of select="appsummary"/><xsl:text>&#10;</xsl:text>
     <xsl:apply-templates/>
   </xsl:template>
 
@@ -271,10 +541,26 @@
   <!-- Func -->
   <xsl:template match="func">
     <xsl:text>&#10;.LP</xsl:text>
-    <xsl:apply-templates/>
+    <xsl:apply-templates select="name"/>
+    <xsl:apply-templates select="fsummary|type|desc"/>
   </xsl:template>
 
   <xsl:template match="name">
+    <xsl:choose>
+      <!-- @arity is mandatory when referring to a specification -->
+      <xsl:when test="string-length(@arity) > 0">
+        <xsl:call-template name="spec_name"/>
+      </xsl:when>
+      <xsl:when test="ancestor::datatype">
+        <xsl:call-template name="type_name"/>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:call-template name="name"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
+  <xsl:template name="name">
     <xsl:text>&#10;.B&#10;</xsl:text>
     <xsl:apply-templates/>
     <xsl:text>&#10;.br</xsl:text>
@@ -296,7 +582,7 @@
     <xsl:text>&#10;</xsl:text><xsl:value-of select="normalize-space(text())"/>
     <xsl:text>&#10;.br</xsl:text>
   </xsl:template>
-  
+
   <!-- D -->
   <xsl:template match="d">
     <xsl:text>&#10;</xsl:text><xsl:apply-templates/>
@@ -316,7 +602,7 @@
     <!-- This tag is skipped for now. -->
   </xsl:template>
 
- 
+
   <!-- Authors -->
   <xsl:template match="authors">
     <xsl:text>&#10;.SH AUTHORS</xsl:text>
@@ -336,21 +622,11 @@
     <xsl:text>&gt;</xsl:text>
   </xsl:template>
 
-  <!-- Do not noramlize any text within pre and code tags. -->
-  <xsl:template match="pre/text()">
-    <xsl:value-of select="."/>
-  </xsl:template>
-
-  <xsl:template match="code/text()">
-    <xsl:value-of select="."/>
-  </xsl:template>
-
-
   <!-- Replace ' by \&' ans . by \&. -->
   <xsl:template match="text()">
     <xsl:variable name="startstring">
       <xsl:value-of select="normalize-space()"/><xsl:text> </xsl:text>
-    </xsl:variable>    
+    </xsl:variable>
     <xsl:variable name="rep1">
       <xsl:call-template name="replace-string">
         <xsl:with-param name="text" select="$startstring" />
-- 
cgit v1.2.3