builtin: make len's godoc less ambiguous

Browse source

The len godoc uses a blockquote to list the rules for its semantics.

The item that describes channels is a bit long, so it's split in two
lines. However, the first line ends with a semicolon, and the second
line can be read as a sentence of its own, so it's easy to misinterpret
that the two lines are separate.

Making that easy mistake would lead to an incorrect understanding of
len:

	if v is nil, len(v) is zero.

This could lead us to think that len(nil) is valid and should return
zero. When in fact, that statement only applies to nil channels.

To make this less ambiguous, add a bit of indentation to the follow-up
line, to align with the channel body. If lists are added to godoc in the
future via #7873, perhaps this text can be simplified.

Fixes #30349.

Change-Id: I84226edc812d429493137bcc65c332e92d4e6c87
Reviewed-on: https://go-review.googlesource.com/c/go/+/167403
Run-TryBot: Daniel Martí <mvdan@mvdan.cc>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Bryan C. Mills <bcmills@google.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

...

This commit is contained in:

Daniel Martí 2019-03-13 17:57:03 +00:00

parent 6aa710f723

commit 1a24bf10bc

1 changed files with 1 additions and 1 deletions

Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL

Download patch file Download diff file Expand all files Collapse all files