spec: more precise prose for built-in function new

1) explain new(type) (simpler) before new(expr) (more complicated)
2) for new(expr), explain what happens when expr is an untyped bool
3) explain that new(nil) is not permitted
4) streamline examples slightly

Fixes #76122.

Change-Id: I5ddb26bd88241b4b2b9aa9b532a62f7861c2341c
Reviewed-on: https://go-review.googlesource.com/c/go/+/722482
Auto-Submit: Robert Griesemer <gri@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Robert Griesemer <gri@google.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
Commit-Queue: Robert Griesemer <gri@google.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/doc/go_spec.html b/doc/go_spec.html
index b75845372da3769e1ad0d080cd65287151cce9f4..b129520180d97417a0f9a4279eaeaaf13a2661e1 100644 (file)
--- a/doc/go_spec.html
+++ b/doc/go_spec.html
@@ -1,6 +1,6 @@
 <!--{
        "Title": "The Go Programming Language Specification",
-       "Subtitle": "Language version go1.26 (Nov 18, 2025)",
+       "Subtitle": "Language version go1.26 (Dec 2, 2025)",
        "Path": "/ref/spec"
 }-->
 
@@ -7794,40 +7794,32 @@ min(x, y, z) == min(min(x, y), z)
 <h3 id="Allocation">Allocation</h3>
 
 <p>
-  The built-in function <code>new</code> creates a new, initialized
-  <a href="#Variables">variable</a> and returns
-  a <a href="#Pointer_types">pointer</a> to it.
-
-  It accepts a single argument, which may be either an expression or a type.
-</p>
-<p>
-  If the argument <code>expr</code> is an expression of
-  type <code>T</code>, or an untyped constant expression
-  whose <a href="#Constants">default type</a> is <code>T</code>,
-  then <code>new(expr)</code> allocates a variable of
-  type <code>T</code>, initializes it to the value
-  of <code>expr</code>, and returns its address, a value of
-  type <code>*T</code>.
+The built-in function <code>new</code> creates a new, initialized
+<a href="#Variables">variable</a> and returns
+a <a href="#Pointer_types">pointer</a> to it.
+It accepts a single argument, which may be either a type or an expression.
 </p>
+
 <p>
-  If the argument is a type <code>T</code>, then <code>new(T)</code>
-  allocates a variable initialized to
-  the <a href="#The_zero_value">zero value</a> of type <code>T</code>.
+If the argument is a type <code>T</code>, then <code>new(T)</code>
+allocates a variable of type <code>T</code> initialized to its
+<a href="#The_zero_value">zero value</a>.
 </p>
-<p>
-  For example, <code>new(123)</code> and <code>new(int)</code> each
-  return a pointer to a new variable of type <code>int</code>.
 
-  The value of the first variable is <code>123</code>, and the value
-  of the second is <code>0</code>.
+<p>
+If the argument is an expression <code>x</code>, then <code>new(x)</code>
+allocates a variable of the type of <code>x</code> initialized to the value of <code>x</code>.
+If that value is an untyped constant, it is first implicitly <a href="#Conversions">converted</a>
+to its <a href="#Constants">default type</a>;
+if it is an untyped boolean value, it is first implicitly converted to type bool.
+The predeclared identifier <code>nil</code> cannot be used as an argument to <code>new</code>.
 </p>
 
-<pre class="grammar">
-new(T)
-</pre>
-
 <p>
-For instance
+For example, <code>new(int)</code> and <code>new(123)</code> each
+return a pointer to a new variable of type <code>int</code>.
+The value of the first variable is <code>0</code>, and the value
+of the second is <code>123</code>. Similarly
 </p>
 
 <pre>
@@ -7836,13 +7828,12 @@ new(S)
 </pre>
 
 <p>
-allocates storage for a variable of type <code>S</code>,
+allocates a variable of type <code>S</code>,
 initializes it (<code>a=0</code>, <code>b=0.0</code>),
 and returns a value of type <code>*S</code> containing the address
-of the location.
+of the variable.
 </p>
 
-
 <h3 id="Handling_panics">Handling panics</h3>
 
 <p> Two built-in functions, <code>panic</code> and <code>recover</code>,