From 743f03eeb0bdcb596b46fae51d23c0fcf0db0474 Mon Sep 17 00:00:00 2001
From: Ian Lance Taylor <iant@golang.org>
Date: Thu, 1 Jul 2021 16:52:59 -0700
Subject: [PATCH] spec, unsafe: clarify unsafe.Slice docs

For #19367

Change-Id: If0ff8ddba3b6b48e2e198cf3653e73284c7572a3
Reviewed-on: https://go-review.googlesource.com/c/go/+/332409
Trust: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Matthew Dempsky <mdempsky@google.com>
Reviewed-by: Robert Griesemer <gri@golang.org>
Reviewed-by: Keith Randall <khr@golang.org>
---
 doc/go_spec.html     | 8 +++++---
 src/unsafe/unsafe.go | 6 ++++--
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/doc/go_spec.html b/doc/go_spec.html
index e0602418e8..ad21ffb1b8 100644
--- a/doc/go_spec.html
+++ b/doc/go_spec.html
@@ -1,6 +1,6 @@
 <!--{
 	"Title": "The Go Programming Language Specification",
-	"Subtitle": "Version of Jun 28, 2021",
+	"Subtitle": "Version of Jul 1, 2021",
 	"Path": "/ref/spec"
 }-->
 
@@ -6782,7 +6782,8 @@ The rules for <a href="/pkg/unsafe#Pointer">valid uses</a> of <code>Pointer</cod
 
 <p>
 The function <code>Slice</code> returns a slice whose underlying array starts at <code>ptr</code>
-and whose length and capacity are <code>len</code>:
+and whose length and capacity are <code>len</code>.
+<code>Slice(ptr, len)</code> is equivalent to
 </p>
 
 <pre>
@@ -6790,7 +6791,8 @@ and whose length and capacity are <code>len</code>:
 </pre>
 
 <p>
-As a special case, if <code>ptr</code> is <code>nil</code> and <code>len</code> is zero,
+except that, as a special case, if <code>ptr</code>
+is <code>nil</code> and <code>len</code> is zero,
 <code>Slice</code> returns <code>nil</code>.
 </p>
 
diff --git a/src/unsafe/unsafe.go b/src/unsafe/unsafe.go
index eaf72c9618..16e3890d0b 100644
--- a/src/unsafe/unsafe.go
+++ b/src/unsafe/unsafe.go
@@ -217,11 +217,13 @@ func Alignof(x ArbitraryType) uintptr
 func Add(ptr Pointer, len IntegerType) Pointer
 
 // The function Slice returns a slice whose underlying array starts at ptr
-// and whose length and capacity are len:
+// and whose length and capacity are len.
+// Slice(ptr, len) is equivalent to
 //
 //	(*[len]ArbitraryType)(unsafe.Pointer(ptr))[:]
 //
-// As a special case, if ptr is nil and len is zero, Slice returns nil.
+// except that, as a special case, if ptr is nil and len is zero,
+// Slice returns nil.
 //
 // The len argument must be of integer type or an untyped constant.
 // A constant len argument must be non-negative and representable by a value of type int;