Merge branch 'sverker/add-since-doc/OTP-15460' into maint

* sverker/add-since-doc/OTP-15460:
  Fill in since for multi-clause functions in erlang.erl
  Fix since attribute for troubled function docs
  Add empty 'since' attribute for old modules and functions
  Add since attribute to dtd
  Add "since" attributes in xml for new functions and modules
  erl_docgen: Generate "since" OTP version in html
  erl_interface: Fix doc for return type 'struct hostent'

5 files changed, 124 insertions, 42 deletions

diff --git a/lib/erl_docgen/doc/src/docgen_xml_check.xml b/lib/erl_docgen/doc/src/docgen_xml_check.xml
index 68253edef7..8d6dceef43 100644
--- a/lib/erl_docgen/doc/src/docgen_xml_check.xml
+++ b/lib/erl_docgen/doc/src/docgen_xml_check.xml
@@ -30,7 +30,7 @@
     <date></date>
     <rev></rev>
   </header>
-  <module>docgen_xml_check</module>
+  <module since="OTP R15B">docgen_xml_check</module>
   <modulesummary>Validate XML documentation source code</modulesummary>
   <description>
     <p><c>docgen_xml_check</c> contains functions for validating XML
@@ -39,7 +39,7 @@
 
   <funcs>
     <func>
-      <name>validate(File) -> ok | error | {error, badfile}</name>
+      <name since="OTP R15B">validate(File) -> ok | error | {error, badfile}</name>
       <fsummary>Validate XML source code.</fsummary>
       <type>
 	<v>File = string()</v>
diff --git a/lib/erl_docgen/priv/css/otp_doc.css b/lib/erl_docgen/priv/css/otp_doc.css
index 34c6befb0e..89b278215c 100644
--- a/lib/erl_docgen/priv/css/otp_doc.css
+++ b/lib/erl_docgen/priv/css/otp_doc.css
@@ -71,6 +71,33 @@ a:visited      { color: #1b6ec2; text-decoration: none }
 }
 
 .bold_code   { font-family: mono, Courier, monospace; font-weight: bold }
+
+/* Invisible table for function specs,
+ * just to get since-version out in right margin */
+.func-table, .func-tr, .func-td, .func-since-td {
+    width: 200%;
+    border: 0;
+    padding: 0;
+    margin: 0;
+}
+
+.func-tr:nth-child(n) {
+    background: inherit  /* turn off zebra striped rows */
+}
+
+.func-td {
+    width: 50%
+}
+
+.func-since-td {
+    width: 50%;
+    padding-left: 1em
+}
+
+.func-td:hover {
+ background-color: #f5f5f5;
+}
+
 .code        {
  font-family: mono, Courier, monospace;
  font-weight: normal;
@@ -283,3 +310,9 @@ a > .code {
 .func-types-title{
  font-size: 1em;
 }
+
+.since{
+    color: gray;
+    font-weight: normal;
+    font-size: small;
+}
\ No newline at end of file
diff --git a/lib/erl_docgen/priv/dtd/cref.dtd b/lib/erl_docgen/priv/dtd/cref.dtd
index 5ccd98ed89..d392081807 100644
--- a/lib/erl_docgen/priv/dtd/cref.dtd
+++ b/lib/erl_docgen/priv/dtd/cref.dtd
@@ -30,6 +30,8 @@
 <!-- `name' is used in common.refs.dtd and must therefore 
       be defined in each *ref. dtd -->
 <!ELEMENT name                (ret,nametext) >
+<!ATTLIST name                 since CDATA #IMPLIED>
+
 <!ELEMENT ret                 (#PCDATA) >
 <!ELEMENT nametext            (#PCDATA) >
 
diff --git a/lib/erl_docgen/priv/dtd/erlref.dtd b/lib/erl_docgen/priv/dtd/erlref.dtd
index 78d6771f52..8202ea5a4d 100644
--- a/lib/erl_docgen/priv/dtd/erlref.dtd
+++ b/lib/erl_docgen/priv/dtd/erlref.dtd
@@ -25,6 +25,7 @@
 <!ELEMENT erlref              (header,module,modulesummary,description, 
 			       (section|funcs|datatypes)*,authors?) >
 <!ELEMENT module              (#PCDATA) >
+<!ATTLIST module               since CDATA #IMPLIED>
 <!ELEMENT modulesummary       (#PCDATA) >
 
 <!-- `name' is used in common.refs.dtd and must therefore 
@@ -34,4 +35,5 @@
                                arity CDATA #IMPLIED
 	                       clause_i CDATA #IMPLIED
                                anchor CDATA #IMPLIED
+	                       since CDATA #IMPLIED
                                n_vars CDATA #IMPLIED>
diff --git a/lib/erl_docgen/priv/xsl/db_html.xsl b/lib/erl_docgen/priv/xsl/db_html.xsl
index a0a922216b..c5150d447c 100644
--- a/lib/erl_docgen/priv/xsl/db_html.xsl
+++ b/lib/erl_docgen/priv/xsl/db_html.xsl
@@ -191,6 +191,7 @@
     <xsl:variable name="name" select="@name"/>
     <xsl:variable name="arity" select="@arity"/>
     <xsl:variable name="anchor" select="@anchor"/>
+    <xsl:variable name="since" select="@since"/>
     <xsl:variable name="spec0">
       <xsl:call-template name="find_spec"/>
     </xsl:variable>
@@ -225,11 +226,12 @@
         <xsl:variable name="global_types" select="ancestor::erlref/datatypes"/>
 	<xsl:variable name="local_types"
 		      select="../type[string-length(@name) > 0]"/>
-	<xsl:apply-templates select="$spec/contract/clause/head">
+	  <xsl:apply-templates select="$spec/contract/clause/head">
           <xsl:with-param name="ghlink" select="ancestor-or-self::*[@ghlink]/@ghlink"/>
 	  <xsl:with-param name="local_types" select="$local_types"/>
 	  <xsl:with-param name="global_types" select="$global_types"/>
-	</xsl:apply-templates>
+	  <xsl:with-param name="since" select="$since"/>
+	  </xsl:apply-templates>
       </xsl:when>
     </xsl:choose>
   </xsl:template>
@@ -238,19 +240,32 @@
     <xsl:param name="ghlink"/>
     <xsl:param name="local_types"/>
     <xsl:param name="global_types"/>
+    <xsl:param name="since"/>
     <xsl:variable name="id" select="concat(concat(concat(concat(../../../name,'-'),../../../arity),'-'),generate-id(.))"/>
-    <div class="bold_code func-head"
-         onMouseOver="document.getElementById('ghlink-{$id}').style.visibility = 'visible';"
-         onMouseOut="document.getElementById('ghlink-{$id}').style.visibility = 'hidden';">
-      <xsl:call-template name="ghlink">
-        <xsl:with-param name="ghlink" select="$ghlink"/>
-        <xsl:with-param name="id" select="$id"/>
-      </xsl:call-template>
-      <xsl:apply-templates mode="local_type">
-        <xsl:with-param name="local_types" select="$local_types"/>
-        <xsl:with-param name="global_types" select="$global_types"/>
-      </xsl:apply-templates>
-    </div>
+    <table class="func-table">
+    <tr class="func-tr">
+    <td class="func-td">
+      <div class="bold_code func-head"
+           onMouseOver="document.getElementById('ghlink-{$id}').style.visibility = 'visible';"
+           onMouseOut="document.getElementById('ghlink-{$id}').style.visibility = 'hidden';">
+	<xsl:call-template name="ghlink">
+          <xsl:with-param name="ghlink" select="$ghlink"/>
+          <xsl:with-param name="id" select="$id"/>
+	</xsl:call-template>
+	<xsl:apply-templates mode="local_type">
+	  <xsl:with-param name="local_types" select="$local_types"/>
+	  <xsl:with-param name="global_types" select="$global_types"/>
+	</xsl:apply-templates>
+      </div>
+    </td>
+    <td class="func-since-td">
+      <xsl:if test="string-length($since) > 0">
+	<span class="since"><xsl:value-of select="$since"/>
+	</span>
+      </xsl:if>
+    </td>
+    </tr>
+    </table>
   </xsl:template>
 
   <!-- The *last* <name name="..." arity=".."/> -->
@@ -1884,6 +1899,16 @@
         <xsl:with-param name="partnum" select="$partnum"/>
       </xsl:apply-templates>
     </div>
+    <!-- Since -->
+    <xsl:if test="string-length(../module/@since) > 0">
+      <xsl:call-template name="h3_title_link">
+	<xsl:with-param name="title">Since</xsl:with-param>
+      </xsl:call-template>
+      <div class="REFBODY module-since">
+	Module <xsl:value-of select="../module"/> was introduced in
+	<xsl:value-of select="../module/@since"/>.
+      </div>
+    </xsl:if>
   </xsl:template>
 
   <!-- Lib -->
@@ -2030,11 +2055,10 @@
   <xsl:template match="func">
     <xsl:param name="partnum"/>
 
-    <p><xsl:apply-templates select="name"/>
-       <xsl:apply-templates
-           select="name[string-length(@arity) > 0 and position()=last()]"
-           mode="types"/>
-    </p>
+    <xsl:apply-templates select="name"/>
+    <xsl:apply-templates
+        select="name[string-length(@arity) > 0 and position()=last()]"
+        mode="types"/>
 
     <xsl:apply-templates select="fsummary|type|desc">
       <xsl:with-param name="partnum" select="$partnum"/>
@@ -2093,19 +2117,29 @@
 
     <xsl:choose>
       <xsl:when test="ancestor::cref">
-        <span class="bold_code bc-7">
-          <xsl:call-template name="title_link">
-            <xsl:with-param name="link" select="substring-before(nametext, '(')"/>
-            <xsl:with-param name="title">
-              <xsl:value-of select="ret"/>
-              <xsl:call-template name="maybe-space-after-ret">
-                <xsl:with-param name="s" select="ret"/>
-              </xsl:call-template>
-              <xsl:value-of select="nametext"/>
-            </xsl:with-param>
-          </xsl:call-template>
-        </span>
-        <br/>
+	<table class="func-table">
+	  <tr class="func-tr">
+	    <td class="func-td">
+              <span class="bold_code bc-7">
+		<xsl:call-template name="title_link">
+		  <xsl:with-param name="link" select="substring-before(nametext, '(')"/>
+		  <xsl:with-param name="title">
+		    <xsl:value-of select="ret"/>
+		    <xsl:call-template name="maybe-space-after-ret">
+                      <xsl:with-param name="s" select="ret"/>
+		    </xsl:call-template>
+		    <xsl:value-of select="nametext"/>
+		  </xsl:with-param>
+		</xsl:call-template>
+              </span>
+	    </td>
+	    <td class="func-since-td">
+	      <xsl:if test="string-length(@since) > 0">
+		<span class="since"><xsl:value-of select="@since"/></span>
+	      </xsl:if>
+	    </td>
+	  </tr>
+	</table>
       </xsl:when>
       <xsl:when test="ancestor::erlref">
         <xsl:variable name="fname">
@@ -2136,14 +2170,25 @@
             </div>
 	  </xsl:when>
           <xsl:otherwise>
-            <div class="bold_code fun-type">
-              <xsl:call-template name="title_link">
-                <xsl:with-param name="link" select="concat(concat($fname,'-'),$arity)"/>
-                <xsl:with-param name="title">
-                  <xsl:apply-templates/>
-                </xsl:with-param>
-              </xsl:call-template>
-            </div>
+	    <table class="func-table">
+	      <tr class="func-tr">
+	      <td class="func-td">
+		<div class="bold_code fun-type">
+		  <xsl:call-template name="title_link">
+                    <xsl:with-param name="link" select="concat(concat($fname,'-'),$arity)"/>
+                    <xsl:with-param name="title">
+                      <xsl:apply-templates/>
+                    </xsl:with-param>
+		  </xsl:call-template>
+		</div>
+	      </td>
+	      <td class="func-since-td">
+		<xsl:if test="string-length(@since) > 0">
+		  <span class="since"><xsl:value-of select="@since"/></span>
+		</xsl:if>
+	      </td>
+	      </tr>
+	    </table>
           </xsl:otherwise>
 	</xsl:choose>
       </xsl:when>