From f330a3a987aa980d6c1adfb4ed509b461d5c13cf Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Tue, 7 Jun 2022 00:02:29 -0400 Subject: [PATCH] doc/go1.19: complete most remaining TODOs The ones I left behind are almost entirely ones that I see pending CLs for. Also make various fixes to existing text. For #51400. Change-Id: I555e0074c9df82b5bdb345e21a08c8757ca147b4 Reviewed-on: https://go-review.googlesource.com/c/go/+/410814 Reviewed-by: Ian Lance Taylor Reviewed-by: Michael Pratt --- doc/go1.19.html | 325 +++++++++++++++++++++++++++++------------------- 1 file changed, 199 insertions(+), 126 deletions(-) diff --git a/doc/go1.19.html b/doc/go1.19.html index d73f635344..4276e9ffea 100644 --- a/doc/go1.19.html +++ b/doc/go1.19.html @@ -20,12 +20,26 @@ Do not send CLs removing the interior tags from such phrases.

Changes to the language

-

- TODO: complete this section -

- TODO: https://go.dev/issue/52038: adjust scope of type parameters declared by method receivers + There is only one small change to the language, + a very small correction + to the scope of type parameters in method declarations. + Existing programs are unaffected. +

+ +

Memory Model

+ +

+ The Go memory model has been revised to align Go with + the memory model used by C, C++, Java, JavaScript, Rust, and Swift. + Go only provides sequentially consistent atomics, not any of the more relaxed forms found in other languages. + Along with the memory model update, + Go 1.19 introduces new types in the sync/atomic package + that make it easier to use atomic values, such as + atomic.Int64 + and + atomic.Pointer[T].

Ports

@@ -37,16 +51,34 @@ Do not send CLs removing the interior tags from such phrases.

Tools

-

- TODO: complete this section, or delete if not needed -

-

: - TODO: https://go.dev/issue/47528 warn when errors.As target has type *error -

Doc Comments

-

- TODO: complete this section. + +

+Go 1.19 adds support for links, lists, and clearer headings in doc comments. +As part of this change, gofmt +now reformats doc comments to make their rendered meaning clearer. +See “Go Doc Comments” +for syntax details and descriptions of common mistakes now highlighted by gofmt. +As another part of this change, the new package go/doc/comment +provides parsing and reformatting of doc comments +as well as support for rendering them to HTML, Markdown, and text. +

+ +

New unix build constraint

+ +

+ The build constraint unix is now recognized + in //go:build lines. The constraint is satisfied + if the target operating system, also known as GOOS, is + a Unix or Unix-like system. For the 1.19 release it is satisfied + if GOOS is one of + aix, android, darwin, + dragonfly, freebsd, hurd, + illumos, ios, linux, + netbsd, openbsd, or solaris. + In future releases the unix constraint may match + additional newly supported operating systems.

Go command

@@ -82,21 +114,13 @@ Do not send CLs removing the interior tags from such phrases. and GOGCCFLAGS variables it reports.

+

Vet

-

New unix build constraint

- -

- The build constraint unix is now recognized - in //go:build lines. The constraint is satisfied - if the target operating system, also known as GOOS, is - a Unix or Unix-like system. For the 1.19 release it is satisfied - if GOOS is one of - aix, android, darwin, - dragonfly, freebsd, hurd, - illumos, ios, linux, - netbsd, openbsd, or solaris. - In future releases the unix constraint may match - additional newly supported operating systems. +

: + The vet checker “errorsas” now reports when + errors.As is called + with a second argument of type *error, + a common mistake.

Runtime

@@ -149,13 +173,18 @@ Do not send CLs removing the interior tags from such phrases. space on below-average goroutines.

-

+

On Unix operating systems, Go programs that import package os now automatically increase the open file limit - (RLIMIT_NOFILE) to the maximum allowed value. Programs that need - a lower limit (for compatibility with select, for example) can - set the limit back as needed, or lower the hard limit prior to starting the - Go program. + (RLIMIT_NOFILE) to the maximum allowed value; + that is, they change the soft limit to match the hard limit. + This corrects artificially low limits set on some systems for compatibility with very old C programs using the + select system call. + Go programs are not helped by that limit, and instead even simple programs like gofmt + often ran out of file descriptors on such systems when processing many files in parallel. + One impact of this change is that Go programs that in turn execute very old C programs in child processes + may run those programs with too high a limit. + This can be corrected by setting the hard limit before invoking the Go program.

@@ -174,7 +203,8 @@ Do not send CLs removing the interior tags from such phrases.

- TODO: https://go.dev/issue/44853: enable address sanitizer in Go + The address sanitizer support added in Go 1.18 + now handles function arguments and global variables more precisely.

Compiler

@@ -218,11 +248,8 @@ Do not send CLs removing the interior tags from such phrases.

Core library

-

- TODO: complete this section -

-

New atomic types

+

The sync/atomic package defines new atomic types Bool, @@ -238,46 +265,46 @@ Do not send CLs removing the interior tags from such phrases. the need to convert to unsafe.Pointer at call sites. Int64 and - Uint64 automatically - receive 64-bit alignment on ARM, 386, and 32-bit MIPS required for 64-bit - atomics on these systems. -

- -

Doc comment parsing

- -

- TODO: https://go.dev/cl/384265: go/doc: use go/doc/comment; modified api/next/51082.txt - TODO: https://go.dev/cl/397276: go/doc/comment: add data structures; modified api/next/51082.txt - TODO: https://go.dev/cl/397278: go/doc/comment: add paragraph parsing and test framework; modified api/next/51082.txt - TODO: https://go.dev/cl/397279: go/doc/comment: add Printer and basic comment printing; modified api/next/51082.txt - TODO: https://go.dev/cl/397281: go/doc/comment: parse and print doc links; modified api/next/51082.txt - TODO: https://go.dev/cl/397284: go/doc/comment: parse and print headings; modified api/next/51082.txt + Uint64 are + automatically aligned to 64-bit boundaries in structs and allocated data, + even on 32-bit systems.

PATH lookups

-

- TODO: https://go.dev/issue/43724: return error when PATH lookup would use current directory +

+ + Command and + LookPath no longer + allow results from a PATH search to be found relative to the current directory. + This removes a common source of security problems + but may also break existing programs that depend on using, say, exec.Command("prog") + to run a binary named prog (or, on Windows, prog.exe) in the current directory. + See the os/exec package documentation for + information about how best to update such programs.

+

- TODO: https://go.dev/issue/43947: on Windows use NeedCurrentDirectoryForExePathW for LookPath behavior + On Windows, Command and LookPath now respect the + NoDefaultCurrentDirectoryInExePath + environment variable, making it possible to disable + the default implicit search of “.” in PATH lookups on Windows systems.

-

Minor changes to the library

As always, there are various minor changes and updates to the library, made with the Go 1 promise of compatibility in mind. -

-

- TODO: complete this section + There are also various performance improvements, not enumerated here.

archive/zip

- TODO: https://go.dev/cl/387976: permit zip files to have prefixes + Reader + now ignores non-ZIP data at the start of a ZIP file, matching most other implementations. + This is necessary to read some Java JAR files, among other uses.

@@ -315,8 +342,8 @@ Do not send CLs removing the interior tags from such phrases.
crypto/x509

- CreateCertificate - no longer supports creating certificates with SignatureAlgorithm + CreateCertificate + no longer supports creating certificates with SignatureAlgorithm set to MD5WithRSA.

@@ -344,8 +371,8 @@ Do not send CLs removing the interior tags from such phrases. To support this addition, RevocationList adds new fields RawIssuer, Signature, AuthorityKeyId, and Extensions. - - The new method RevocationList.CheckSignatureFrom + + The new method RevocationList.CheckSignatureFrom checks that the signature on a CRL is a valid signature from a Certificate. @@ -358,7 +385,7 @@ Do not send CLs removing the interior tags from such phrases.

When building paths, Certificate.Verify - now considers certificates to be equal when the subjects, public keys, and SANs + now considers certificates to be equal when the subjects, public keys, and SANs are all equal. Before, it required byte-for-byte equality.

@@ -395,19 +422,19 @@ Do not send CLs removing the interior tags from such phrases.
debug

- TODO: https://go.dev/cl/396735: debug: define ELF relocation for loong64; modified api/next/46229.txt + The new EM_LONGARCH and R_LARCH_* constants + support the loong64 port.

debug/pe
-

- TODO: https://go.dev/issue/51868: add APIs to support reading COMDAT info for sections -

- -

- TODO: https://go.dev/cl/394534: debug/pe: add APIs for reading section def aux info; modified api/next/51868.txt +

+ The new File.COFFSymbolReadSectionDefAux + method, which returns a COFFSymbolAuxFormat5, + provides access to COMDAT information in PE file sections. + These are supported by new IMAGE_COMDAT_* and IMAGE_SCN_* constants.

@@ -415,19 +442,32 @@ Do not send CLs removing the interior tags from such phrases.
encoding/binary

- TODO: https://go.dev/cl/386017: add AppendByteOrder + The new interface + AppendByteOrder + provides efficient methods for appending a uint16, uint32, or uint64 + to a byte slice. + BigEndian and + LittleEndian now implement this interface.

- TODO: https://go.dev/issue/51644: add AppendUvarint and AppendVarint + Similarly, the new functions + AppendUvarint and + AppendVarint + are efficient appending versions of + PutUvarint and + PutVarint.

-
encoding/csv

- TODO: https://go.dev/cl/405675: add Reader.InputOffset method + The new method + Reader.InputOffset + reports the reader's current input position as a byte offset, + analogous to encoding/json's + Decoder.InputOffset.

@@ -435,8 +475,11 @@ Do not send CLs removing the interior tags from such phrases.
encoding/xml

- TODO: https://go.dev/issue/45628: add Decoder.InputPos - TODO: https://go.dev/cl/311270: encoding/xml: expose decoder line and column; modified api/next/45628.txt + The new method + Decoder.InputPos + reports the reader's current input position as a line and column, + analogous to encoding/csv's + Decoder.FieldPos.

@@ -444,7 +487,14 @@ Do not send CLs removing the interior tags from such phrases.
flag

- TODO: https://go.dev/cl/313329: add TextVar function + The new function + TextVar + defines a flag with a value implementing + encoding.TextUnmarshaler, + allowing command-line flag variables to have types such as + big.Int, + netip.Addr, and + time.Time.

@@ -452,7 +502,11 @@ Do not send CLs removing the interior tags from such phrases.
fmt

- TODO: https://go.dev/cl/406177: add Append, Appendln, Appendf + The new functions + Append, + Appendf, and + Appendln + append formatted data to byte slices.

@@ -460,7 +514,9 @@ Do not send CLs removing the interior tags from such phrases.
go/parser

- TODO: https://go.dev/cl/403696: parser to accept ~x as unary expression + The parser now recognizes ~x as a unary expression with operator + token.TILDE, + allowing better error recovery when a type constraint such as ~int is used in an incorrect context.

@@ -489,8 +545,14 @@ Do not send CLs removing the interior tags from such phrases.
hash/maphash

- TODO: https://go.dev/cl/392494: hash/maphash: add Bytes and String; modified api/next/42710.txt - TODO: https://go.dev/issue/42710: add Bytes and String + The new functions + Bytes + and + String + provide an efficient way hash a single byte slice or string. + They are equivalent to using the more general + Hash + with a single write, but they avoid setup overhead for small inputs.

@@ -498,8 +560,11 @@ Do not send CLs removing the interior tags from such phrases.
html/template

- TODO: https://go.dev/issue/46121: make FuncMap an alias for text/template.FuncMap - TODO: https://go.dev/cl/389156: html/template: make FuncMap a type alias of text/template.FuncMap; modified api/except.txt, api/next/46121.txt + The type FuncMap + is now an alias for + text/template's FuncMap + instead of its own named type. + This allows writing code that operates on a FuncMap from either setting.

@@ -507,11 +572,13 @@ Do not send CLs removing the interior tags from such phrases.
image/draw

- Draw with the Src operator preserves + Draw with the + Src operator preserves non-premultiplied-alpha colors when destination and source images are - both *image.NRGBA (or both *image.NRGBA64). + both image.NRGBA + or both image.NRGBA64. This reverts a behavior change accidentally introduced by a Go 1.18 - library optimization, to match the behavior in Go 1.17 and earlier. + library optimization; the code now matches the behavior in Go 1.17 and earlier.

@@ -519,11 +586,16 @@ Do not send CLs removing the interior tags from such phrases.
io

- TODO: https://go.dev/cl/400236: NopCloser forward WriterTo implementations if the reader supports it + NopCloser's result now implements + WriterTo + whenever its input does.

- TODO: https://go.dev/issue/50842: implement WriterTo on result of MultiReader + MultiReader's result now implements + WriterTo unconditionally. + If any underlying reader does not implement WriterTo, + it is simulated appropriately.

@@ -539,7 +611,7 @@ Do not send CLs removing the interior tags from such phrases. type text/javascript; charset=utf-8. Applications that expect text/plain on Windows must now explicitly call - AddExtensionType. + AddExtensionType.

@@ -569,6 +641,7 @@ Do not send CLs removing the interior tags from such phrases. package function or method to return an error, while preserving backward compatibility for error messages.

+

Resolver.PreferGo is now implemented on Windows and Plan 9. It previously only worked on Unix @@ -578,6 +651,7 @@ Do not send CLs removing the interior tags from such phrases. possible to write portable programs and be in control of all DNS name lookups when dialing.

+

The net package now has initial support for the netgo build tag on Windows. When used, the package uses the Go DNS client (as used @@ -636,26 +710,17 @@ Do not send CLs removing the interior tags from such phrases. -

os
-
-

- TODO: https://go.dev/cl/392415: raise open file rlimit at startup -

-
-
- -
os/exec

- An exec.Cmd with a non-empty Dir and a - nil Env now implicitly sets the PWD environment + A Cmd with a non-empty Dir field + and nil Env now implicitly sets the PWD environment variable for the subprocess to match Dir.

- The new method (*exec.Cmd).Environ reports the + The new method Cmd.Environ reports the environment that would be used to run the command, including the - aforementioned PWD variable. + implicitly set PWD variable.

@@ -663,37 +728,36 @@ Do not send CLs removing the interior tags from such phrases.
reflect

- The method Value.Bytes now accepts addressable arrays in addition to slices. + The method Value.Bytes + now accepts addressable arrays in addition to slices.

- The methods Value.Len and Value.Cap now successfully operate on a pointer to an array and return the length of that array, to match what the builtin len and cap functions do. + The methods Value.Len + and Value.Cap + now successfully operate on a pointer to an array and return the length of that array, + to match what the builtin + len and cap functions do.

-
regexp
+
regexp/syntax

- TODO: https://go.dev/issue/51684: add ErrNestingDepth error - TODO: https://go.dev/cl/401076: regexp: change ErrInvalidDepth message to match proposal; modified api/next/51684.txt, api/next/regexpdepth.txt + Go 1.18 release candidate 1, Go 1.17.8, and Go 1.16.15 included a security fix + to the regular expression parser, making it reject very deeply nested expressions. + Because Go patch releases do not introduce new API, + the parser returned syntax.ErrInternalError in this case. + Go 1.19 adds a more specific error, syntax.ErrNestingDepth, + which the parser now returns instead.

-
regexp/syntax
-
-

- TODO: https://go.dev/cl/384617: regexp/syntax: add and use ErrInvalidDepth; modified api/next/regexpdepth.txt - TODO: https://go.dev/cl/401854: regexp/syntax: rename ErrInvalidDepth to ErrNestingDepth; modified api/next/51684.txt -

-
-
- -
runtime

- The GOROOT function now returns the empty string + The GOROOT function now returns the empty string (instead of "go") when the binary was built with the -trimpath flag set and the GOROOT variable is not set in the process environment. @@ -797,8 +861,11 @@ Do not send CLs removing the interior tags from such phrases. is faster for several common scenarios.

- TODO: https://go.dev/issue/50340: add Find - TODO: https://go.dev/cl/396514: sort: add Find function; modified api/next/50340.txt + The new function + Find + is like + Search + but often easier to use: it returns an additional boolean reporting whether an equal value was found.

@@ -808,8 +875,9 @@ Do not send CLs removing the interior tags from such phrases.

Quote - and related functions now quote the rune 007F as \x7f, - not \u007f. + and related functions now quote the rune U+007F as \x7f, + not \u007f, + for consistency with other ASCII values.

@@ -835,12 +903,17 @@ Do not send CLs removing the interior tags from such phrases.
time

- TODO: https://go.dev/cl/393515: add Duration.Abs - TODO: https://go.dev/issue/51414: add Duration.Abs + The new method + Duration.Abs + provides a convenient and safe way to take the absolute value of a duration, + converting −2⁶³ to 2⁶³−1. + (This boundary case can happen as the result of subtracting a recent time from the zero time.)

- TODO: https://go.dev/issue/50062: add Time.ZoneBounds - TODO: https://go.dev/cl/405374: time: add Time.ZoneBounds; modified api/next/50062.txt + The new method + Time.ZoneBounds + returns the start and end times of the time zone in effect at a given time. + It can be used in a loop to enumerate all the known time zone transitions at a given location.

-- 2.48.1