doc/go1.10: process comments from CL 78131 PS 5

Change-Id: Ie246756452cd872961aeb659b35297c229504a3c
Reviewed-on: https://go-review.googlesource.com/81936Reviewed-by: Russ Cox <rsc@golang.org>

doc/go1.10.html

@@ -22,6 +22,16 @@ ul li { margin: 0.5em 0; }
   release notes. Go 1.10 is expected to be released in February 2018.
 </strong></p>
 
+<!-- TODO: not sure about these relnotes
+
+cmd/compile
+  https://golang.org/cl/60410: cmd/compile: fix and improve struct field reflect information
+encoding/json
+  https://golang.org/cl/76851: encoding/json: always ignore embedded pointers to unexported struct types
+runtime
+  https://golang.org/cl/59970: runtime: separate soft and hard heap limits
+-->
+
 <p>
 The latest Go release, version 1.10, arrives six months after <a href="go1.9">go1.9</a>.
 Most of its changes are in the implementation of the toolchain, runtime, and libraries.
@@ -141,8 +151,8 @@ The new build cache makes future commands still run as quickly as if the
 dependencies had been installed.
 To force the installation of dependencies, use the new 
 <code>go</code> <code>install</code> <code>-i</code> flag.
-Installing dependencies should not be necessary in general,
-and the very concept or installed packages may disappear in a future release.
+Installing dependency packages should not be necessary in general,
+and the very concept of installed packages may disappear in a future release.
 </p>
 
 <p>
@@ -208,7 +218,7 @@ merging most of the time.
 <p>
 The <code>go</code>&nbsp;<code>test</code> <code>-v</code> output
 now includes <code>PAUSE</code> and <code>CONT</code> status update
-lines to make clearer when <a href="/pkg/testing/#T.Parallel">parallel tests</a> pause and continue.
+lines to mark when <a href="/pkg/testing/#T.Parallel">parallel tests</a> pause and continue.
 </p>
 
 <p>
@@ -320,13 +330,14 @@ without the binary that produced the profile.
 
 <p>
 The <a href="/cmd/pprof/"><code>go</code>&nbsp;<code>tool</code>&nbsp;<code>pprof</code></a> profile visualizer has been updated to
-the latest version from <a href="https://github.com/google/pprof">github.com/google/pprof</a>.
+the latest version from <a href="https://github.com/google/pprof">github.com/google/pprof</a>,
+which includes an updated web interface.
 </p>
 
 <h3 id="vet">Vet</h3>
 
 <p>
-The <a href="/cmd/pprof/"><code>go</code>&nbsp;<code>vet</code></a> command now always has access to
+The <a href="/cmd/vet/"><code>go</code>&nbsp;<code>vet</code></a> command now always has access to
 complete, up-to-date type information when checking packages, even for packages using cgo or vendored imports.
 The reports should be more accurate as a result.
 Note that only <code>go</code>&nbsp;<code>vet</code> has access to this information;
@@ -386,9 +397,10 @@ spread fairly evenly across the supported architectures.
 </p>
 
 <p>
-TODO: What to say about DWARF work, if anything?
-Global constants (CL 61019), variable decomposition (CL 50878), variable liveness and location lists (CL 41770), more?
-What is enabled by default?
+The DWARF debug information recorded in binaries has been improved in a few ways:
+constant values are now recorded;
+line number information is more accurate, making source-level stepping through a program work better;
+and each package is now presented as its own DWARF compilation unit.
 </p>
 
 <p>
@@ -493,8 +505,8 @@ instructions.
 </p>
 
 <p>
-For the X86 64-bit port, the assembler now supports 359 new instructions
-and is believed to be complete up to and including the Intel AVX-256 extensions.
+For the X86 64-bit port, the assembler now supports 359 new instructions,
+including the full AVX, AVX2, BMI, BMI2, F16C, FMA3, SSE2, SSE3, SSSE3, SSE4.1, and SSE4.2 extension sets.
 The assembler also no longer implements <code><small>MOVL</small></code>&nbsp;<code><small>$0,</small></code>&nbsp;<code><small>AX</small></code>
 as an <code><small>XORL</small></code> instruction,
 to avoid clearing the condition flags unexpectedly.
@@ -509,12 +521,35 @@ TODO: Words about GCC 8 and Go 1.10.
 <h2 id="runtime">Runtime</h2>
 
 <p>
-TODO: Don't start new threads from locked threads or threads that Go did not create. LockOSThread/UnlockOSThread now nest. LockOSThread + return kills the thread
+The behavior of nested calls to
+<a href="/pkg/runtime/#LockOSThread"><code>LockOSThread</code></a> and
+<a href="/pkg/runtime/#UnlockOSThread"><code>UnlockOSThread</code></a>
+has changed.
+These functions control whether a goroutine is locked to a specific operating system thread,
+so that the goroutine only runs on that thread, and the thread only runs that goroutine.
+Previously, calling <code>LockOSThread</code> more than once in a row
+was equivalent to calling it once, and a single <code>UnlockOSThread</code>
+always unlocked the thread.
+Now, the calls nest: if <code>LockOSThread</code> is called multiple times,
+<code>UnlockOSThread</code> must be called the same number of times
+in order to unlock the thread.
+Existing code that was careful not to nest these calls will remain correct.
+Existing code that incorrectly assumed the calls nested will become correct.
+Most uses of these functions in public Go source falls into the second category.
+</p>
+
+<p>
+Because one common use of <code>LockOSThread</code> and <code>UnlockOSThread</code>
+is to allow Go code to reliably modify thread-local state (for example, Linux or Plan 9 name spaces),
+the runtime now treats locked threads as unsuitable for reuse or for creating new threads.
 </p>
 
 <p>
 Stack traces no longer include implicit wrapper functions (previously marked <code>&lt;autogenerated&gt;</code>),
 unless a fault or panic happens in the wrapper itself.
+As a result, skip counts passed to functions like <a href="/pkg/runtime/#Caller"><code>Caller</code></a>
+should now always match the structure of the code as written, rather than depending on
+optimization decisions and implementation details.
 </p>
 
 <p>
@@ -534,7 +569,7 @@ better generated code, and optimizations in the core library.
 <h2 id="gc">Garbage Collector</h2>
 
 <p>
-TODO: Anything?
+Many applications should experience significantly lower allocation latency and overall performance overhead when the garbage collector is active.
 </p>
 
 <h2 id="library">Core library</h2>
@@ -571,12 +606,13 @@ The new <a href="/pkg/archive/tar/#Header"><code>Header.Format</code></a> field
 of type <a href="/pkg/archive/tar/#Format"><code>Format</code></a>
 controls which tar header format the <a href="/pkg/archive/tar/#Writer"><code>Writer</code></a> uses.
 The default, as before, is to select the most widely-supported header type
-that can encoding the fields needed by the header (USTAR if possible, or else PAX if possible, or else GNU).
+that can encode the fields needed by the header (USTAR if possible, or else PAX if possible, or else GNU).
 The <a href="/pkg/archive/tar/#Reader"><code>Reader</code></a> sets <code>Header.Format</code> for each header it reads.
 </p>
 <p>
-<code>Reader</code> and the <code>Writer</code> now support PAX records,
-using the new <a href="/pkg/archive/tar/#Header"><code>Header.PAXRecords</code></a> field.
+<code>Reader</code> and the <code>Writer</code> now support arbitrary PAX records,
+using the new <a href="/pkg/archive/tar/#Header"><code>Header.PAXRecords</code></a> field,
+a generalization of the existing <code>Xattrs</code> field.
 </p>
 <p>
 The <code>Reader</code> no longer insists that the file name or link name in GNU headers
@@ -587,10 +623,6 @@ When writing PAX- or GNU-format headers, the <code>Writer</code> now includes
 the <code>Header.AccessTime</code> and <code>Header.ChangeTime</code> fields (if set).
 When writing PAX-format headers, the times include sub-second precision.
 </p>
-<p>
-The <a href="/pkg/archive/tar/#Writer.Flush"><code>Writer.Flush</code></a> method,
-which has had no real effect since Go 1.1, is now marked deprecated.
-</p>
 </dl>
 
 <dl id="archive/zip"><dt><a href="/pkg/archive/zip/">archive/zip</a></dt>
@@ -607,8 +639,9 @@ now support the widely-understood Info-Zip extension that encodes the time separ
 The <a href="/pkg/archive/zip/#FileHeader"><code>FileHeader</code></a>'s new <code>Modified</code> field of type <a href="/pkg/time/#Time"><code>time.Time</code></a>
 obsoletes the <code>ModifiedTime</code> and <code>ModifiedDate</code> fields, which continue to hold the MS-DOS encoding.
 The <code>Reader</code> and <code>Writer</code> now adopt the common
-convention that ZIP archive storing the Unix time encoding store the local time
-in the MS-DOS field, so that the time zone offset can be inferred.
+convention that a ZIP archive storing a time zone-independent Unix time
+also stores the local time in the MS-DOS field,
+so that the time zone offset can be inferred.
 For compatibility, the <a href="/pkg/archive/zip/#FileHeader.ModTime"><code>ModTime</code></a> and
 <a href="/pkg/archive/zip/#FileHeader.SetModTime"><code>SetModTime</code></a> methods
 behave the same as in earlier releases; new code should use <code>Modified</code> directly.
@@ -770,7 +803,7 @@ and
 <p>
 Go 1.10 adds support for reading relocations from Mach-O sections,
 using the <a href="/pkg/debug/macho#Section"><code>Section</code></a> struct's new <code>Relocs</code> field
-and the new<a href="/pkg/debug/macho/#Reloc"><code>Reloc</code></a>,
+and the new <a href="/pkg/debug/macho/#Reloc"><code>Reloc</code></a>,
 <a href="/pkg/debug/macho/#RelocTypeARM"><code>RelocTypeARM</code></a>,
 <a href="/pkg/debug/macho/#RelocTypeARM64"><code>RelocTypeARM64</code></a>,
 <a href="/pkg/debug/macho/#RelocTypeGeneric"><code>RelocTypeGeneric</code></a>,
@@ -846,7 +879,7 @@ When the functions
 and
 <a href="/pkg/encoding/hex/#DecodeString"><code>DecodeString</code></a>
 encounter malformed input,
-they each now return the number of bytes already converted
+they now return the number of bytes already converted
 along with the error.
 Previously they always returned a count of 0 with any error.
 </p>
@@ -857,7 +890,7 @@ Previously they always returned a count of 0 with any error.
 <p>
 The <a href="/pkg/encoding/json/#Decoder"><code>Decoder</code></a>
 adds a new method
-<a href="/pkg/encoding/json/#DisallowUnknownFields"><code>DisallowUnknownFields</code></a>
+<a href="/pkg/encoding/json/#Decoder.DisallowUnknownFields"><code>DisallowUnknownFields</code></a>
 that causes it to report inputs with unknown JSON fields as a decoding error.
 (The default behavior has always been to discard unknown fields.)
 </p>
@@ -872,6 +905,10 @@ and
 no longer generate partial output when presented with a
 block that is impossible to encode as PEM data.
 </p>
+
+<p>
+TODO: Reflect fallout.
+</p>
 </dl>
 
 <dl id="encoding/xml"><dt><a href="/pkg/encoding/xml/">encoding/xml</a></dt>
@@ -1005,7 +1042,7 @@ have been corrected to match the definitions used in the C99 standard.
 <dl id="math/rand"><dt><a href="/pkg/math/rand/">math/rand</a></dt>
 <dd>
 <p>
-The new <a href="/pkg/math/rand/#Shuffle"> function and corresponding
+The new <a href="/pkg/math/rand/#Shuffle"><code>Shuffle</code></a> function and corresponding
 <a href="/pkg/math/rand/#Rand.Shuffle"><code>Rand.Shuffle</code></a> method
 shuffle an input sequence.
 </p>
@@ -1018,9 +1055,9 @@ The new functions
 <a href="/pkg/math/#Round"><code>Round</code></a>
 and
 <a href="/pkg/math/#RoundToEven"><code>RoundToEven</code></a>
-round their arguments to the nearest integer;
+round their arguments to the nearest floating-point integer;
 <code>Round</code> rounds a half-integer to its larger integer neighbor (away from zero)
-while <code>RoundToEven</code> rounds a half-integer its even integer neighbor.
+while <code>RoundToEven</code> rounds a half-integer to its even integer neighbor.
 </p>
 
 <p>
@@ -1112,21 +1149,7 @@ if passed an invalid (non-3-digit) status code.
 <dl id="net/http/httputil"><dt><a href="/pkg/net/http/httputil/">net/http/httputil</a></dt>
 <dd>
 <p>
-The <a href="/pkg/net/http/httputil/#ReverseProxy">ReverseProxy</a> now invokes
-the <code>
-On the client side, an HTTP proxy (most commonly configured by
-<a href="/pkg/net/http/#ProxyFromEnvironment"><code>ProxyFromEnvironment</code></a>)
-can now be specified as an <code>https://</code> URL,
-meaning that the client connects to the proxy over HTTPS before issuing a standard, proxied HTTP request.
-(Previously, HTTP proxy URLs were required to begin with <code>http://</code> or <code>socks5://</code>.)
-</p>
-<p>
-On the server side, <a href="/pkg/net/http/#FileServer"><code>FileServer</code></a> and its single-file equivalent <a href="/pkg/net/http/#ServeFile"><code>ServeFile</code></a>
-now apply <code>If-Range</code> checks to <code>HEAD</code> requests.
-<code>FileServer</code> also now reports directory read failures to the <a href="/pkg/net/http/#Server"><code>Server</code></a>'s <code>ErrorLog</code>.
-</p>
-<p>
-<a href="/pkg/net/http/#Redirect"><code>Redirect</code></a> now sets the <code>Content-Type</code> header before writing its HTTP response.
+TODO: ReverseProxy and back end errors and ModifyResponse.
 </p>
 </dl>
 
@@ -1134,7 +1157,7 @@ now apply <code>If-Range</code> checks to <code>HEAD</code> requests.
 <dd>
 <p>
 <a href="/pkg/net/mail/#ParseAddress"><code>ParseAddress</code></a> and
-<a href="/pkg/net/mail/#ParseAddressList"><code>ParseAddressList</code></a> and
+<a href="/pkg/net/mail/#ParseAddressList"><code>ParseAddressList</code></a>
 now support a variety of obsolete address formats.
 </p>
 </dl>
@@ -1243,6 +1266,10 @@ The <a href="/pkg/reflect/#Copy"><code>Copy</code></a> function now allows copyi
 from a string into a byte array or byte slice, to match the
 <a href="/pkg/builtin/#copy">built-in copy function</a>.
 </p>
+
+<p>
+TODO: New reflect CanSet change for pointers to unexported fields.
+</p>
 </dl>
 
 <dl id="runtime/pprof"><dt><a href="/pkg/runtime/pprof/">runtime/pprof</a></dt>