From eebb9db0ef1a4cad2f5dd7e8b90f699a1d50bf91 Mon Sep 17 00:00:00 2001
From: Robert Griesemer <gri@golang.org>
Date: Thu, 9 May 2019 17:35:29 -0700
Subject: [PATCH] spec: clarify the difference between &T{} and new(T)

Add a small paragraph and example pointing out
the difference for the case where T is a slice
or map. This is a common error for Go novices.

Fixes #29425.

Change-Id: Icdb59f25361e9f6a09b190fbfcc9ae0c7d90077b
Reviewed-on: https://go-review.googlesource.com/c/go/+/176338
Reviewed-by: Matthew Dempsky <mdempsky@google.com>
---
 doc/go_spec.html | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/doc/go_spec.html b/doc/go_spec.html
index 158146b9c00f5..dea3afe498d6c 100644
--- a/doc/go_spec.html
+++ b/doc/go_spec.html
@@ -2513,10 +2513,24 @@ <h3 id="Composite_literals">Composite literals</h3>
 generates a pointer to a unique <a href="#Variables">variable</a> initialized
 with the literal's value.
 </p>
+
 <pre>
 var pointer *Point3D = &amp;Point3D{y: 1000}
 </pre>
 
+<p>
+Note that the <a href="#The_zero_value">zero value</a> for a slice or map
+type is not the same as an initialized but empty value of the same type.
+Consequently, taking the address of an empty slice or map composite literal
+does not have the same effect as allocating a new slice or map value with
+<a href="#Allocation">new</a>.
+</p>
+
+<pre>
+p1 := &[]int{}    // p1 points to an initialized, empty slice with value []int{} and length 0
+p2 := new([]int)  // p2 points to an uninitialized slice with value nil and length 0
+</pre>
+
 <p>
 The length of an array literal is the length specified in the literal type.
 If fewer elements than the length are provided in the literal, the missing