code review 11699043: all: be more idiomatic when documenting boolean return ...

all: be more idiomatic when documenting boolean return values.
Phrases like "returns whether or not the image is opaque" could be
describing what the function does (it always returns, regardless of
the opacity) or what it returns (a boolean indicating the opacity).
Even when the "or not" is missing, the phrasing is bizarre.

Go with "reports whether", which is still clunky but at least makes
it clear we're talking about the return value.

These were edited by hand. A few were cleaned up in other ways.

[r, 2013-07-23 00:28:10]

Hello golang-dev@googlegroups.com,

I'd like you to review this change to
https://code.google.com/p/go/

[dsymonds, 2013-07-23 00:42:21]

LGTM with some of the redundancy trimmed.

https://codereview.appspot.com/11699043/diff/1/src/pkg/crypto/ecdsa/ecdsa.go
File src/pkg/crypto/ecdsa/ecdsa.go (right):

https://codereview.appspot.com/11699043/diff/1/src/pkg/crypto/ecdsa/ecdsa.go#...
src/pkg/crypto/ecdsa/ecdsa.go:127: // return value records whether the signature
is valid.
maybe just make the second sentence "It returns whether ..."?

https://codereview.appspot.com/11699043/diff/1/src/pkg/image/image.go
File src/pkg/image/image.go (right):

https://codereview.appspot.com/11699043/diff/1/src/pkg/image/image.go#newcode129
src/pkg/image/image.go:129: // Opaque scans the entire image and returns a
boolean indicating whether it is fully opaque.
calling it out as a boolean seems unnecessary. that's inherent in the "whether".

// Opaque scans the entire image and returns whether it is fully opaque.

(same below)

https://codereview.appspot.com/11699043/diff/1/src/pkg/os/error.go
File src/pkg/os/error.go (right):

https://codereview.appspot.com/11699043/diff/1/src/pkg/os/error.go#newcode46
src/pkg/os/error.go:46: // IsExist returns a boolean indicating whether the
error is known to report
why insert these words? they are redundant.

https://codereview.appspot.com/11699043/diff/1/src/pkg/regexp/regexp.go
File src/pkg/regexp/regexp.go (right):

https://codereview.appspot.com/11699043/diff/1/src/pkg/regexp/regexp.go#newco...
src/pkg/regexp/regexp.go:379: // RuneReader.  The return value is a boolean:
true for match, false for no
perhaps ditch the redundant second sentences for these docs too?

https://codereview.appspot.com/11699043/diff/1/src/pkg/sort/sort.go
File src/pkg/sort/sort.go (right):

https://codereview.appspot.com/11699043/diff/1/src/pkg/sort/sort.go#newcode15
src/pkg/sort/sort.go:15: // Less returns a boolean indicating whether the
element with
redundant

[r, 2013-07-23 01:59:57]

*** Submitted as https://code.google.com/p/go/source/detail?r=977306015f5d ***

all: be more idiomatic when documenting boolean return values.
Phrases like "returns whether or not the image is opaque" could be
describing what the function does (it always returns, regardless of
the opacity) or what it returns (a boolean indicating the opacity).
Even when the "or not" is missing, the phrasing is bizarre.

Go with "reports whether", which is still clunky but at least makes
it clear we're talking about the return value.

These were edited by hand. A few were cleaned up in other ways.

R=golang-dev, dsymonds
CC=golang-dev
https://codereview.appspot.com/11699043

[magical, 2013-07-23 18:10:03]

https://codereview.appspot.com/11699043/diff/6002/src/pkg/go/ast/ast.go
File src/pkg/go/ast/ast.go (right):

https://codereview.appspot.com/11699043/diff/6002/src/pkg/go/ast/ast.go#newco...
src/pkg/go/ast/ast.go:523: // (that is, whether it begins with an upper-case
letter).
Make these edits below, as well?

https://codereview.appspot.com/11699043/diff/6002/src/pkg/html/template/css.go
File src/pkg/html/template/css.go (right):

https://codereview.appspot.com/11699043/diff/6002/src/pkg/html/template/css.g...
src/pkg/html/template/css.go:102: // isHex reports reports whether the given
character is a hex digit.
s/reports reports/reports/