all: use "reports whether" consistently instead of "returns whether"

Follow-up for CL 147037 and after Brad noticed the "returns whether"
pattern during the review of CL 150621.

Go documentation style for boolean funcs is to say:

    // Foo reports whether ...
    func Foo() bool

(rather than "returns whether")

Created with:

    $ perl -i -npe 's/returns whether/reports whether/' $(git grep -l "returns whether" | grep -v vendor)

Change-Id: I15fe9ff99180ad97750cd05a10eceafdb12dc0b4
Reviewed-on: https://go-review.googlesource.com/c/150918
Run-TryBot: Tobias Klauser <[email protected]>
Reviewed-by: Brad Fitzpatrick <[email protected]>

Author: tklauser

src/bytes/buffer.go

@@ -68,7 +68,7 @@ func (b *Buffer) String() string {
 	return string(b.buf[b.off:])
 }
 
-// empty returns whether the unread portion of the buffer is empty.
+// empty reports whether the unread portion of the buffer is empty.
 func (b *Buffer) empty() bool { return len(b.buf) <= b.off }
 
 // Len returns the number of bytes of the unread portion of the buffer;

src/cmd/cgo/gcc.go

@@ -718,7 +718,7 @@ func (p *Package) mangleName(n *Name) {
 
 // rewriteCalls rewrites all calls that pass pointers to check that
 // they follow the rules for passing pointers between Go and C.
-// This returns whether the package needs to import unsafe as _cgo_unsafe.
+// This reports whether the package needs to import unsafe as _cgo_unsafe.
 func (p *Package) rewriteCalls(f *File) bool {
 	needsUnsafe := false
 	// Walk backward so that in C.f1(C.f2()) we rewrite C.f2 first.
@@ -941,7 +941,7 @@ func (p *Package) rewriteCall(f *File, call *Call) (string, bool) {
 	return sb.String(), needsUnsafe
 }
 
-// needsPointerCheck returns whether the type t needs a pointer check.
+// needsPointerCheck reports whether the type t needs a pointer check.
 // This is true if t is a pointer and if the value to which it points
 // might contain a pointer.
 func (p *Package) needsPointerCheck(f *File, t ast.Expr, arg ast.Expr) bool {
@@ -958,7 +958,7 @@ func (p *Package) needsPointerCheck(f *File, t ast.Expr, arg ast.Expr) bool {
 
 // hasPointer is used by needsPointerCheck. If top is true it returns
 // whether t is or contains a pointer that might point to a pointer.
-// If top is false it returns whether t is or contains a pointer.
+// If top is false it reports whether t is or contains a pointer.
 // f may be nil.
 func (p *Package) hasPointer(f *File, t ast.Expr, top bool) bool {
 	switch t := t.(type) {
@@ -1172,7 +1172,7 @@ func (p *Package) checkAddr(sb, sbCheck *bytes.Buffer, arg ast.Expr, i int) bool
 	return true
 }
 
-// isType returns whether the expression is definitely a type.
+// isType reports whether the expression is definitely a type.
 // This is conservative--it returns false for an unknown identifier.
 func (p *Package) isType(t ast.Expr) bool {
 	switch t := t.(type) {
@@ -1214,7 +1214,7 @@ func (p *Package) isType(t ast.Expr) bool {
 	return false
 }
 
-// isConst returns whether x is an untyped constant expression.
+// isConst reports whether x is an untyped constant expression.
 func (p *Package) isConst(f *File, x ast.Expr) bool {
 	switch x := x.(type) {
 	case *ast.BasicLit:
@@ -2827,7 +2827,7 @@ func (c *typeConv) Struct(dt *dwarf.StructType, pos token.Pos) (expr *ast.Struct
 	return
 }
 
-// dwarfHasPointer returns whether the DWARF type dt contains a pointer.
+// dwarfHasPointer reports whether the DWARF type dt contains a pointer.
 func (c *typeConv) dwarfHasPointer(dt dwarf.Type, pos token.Pos) bool {
 	switch dt := dt.(type) {
 	default:

src/cmd/cgo/out.go

@@ -1203,7 +1203,7 @@ func (p *Package) writeExportHeader(fgcch io.Writer) {
 	fmt.Fprintf(fgcch, "%s\n", p.gccExportHeaderProlog())
 }
 
-// gccgoUsesNewMangling returns whether gccgo uses the new collision-free
+// gccgoUsesNewMangling reports whether gccgo uses the new collision-free
 // packagepath mangling scheme (see determineGccgoManglingScheme for more
 // info).
 func gccgoUsesNewMangling() bool {

src/cmd/compile/internal/gc/reflect.go

@@ -915,7 +915,7 @@ func dcommontype(lsym *obj.LSym, t *types.Type) int {
 	return ot
 }
 
-// typeHasNoAlg returns whether t does not have any associated hash/eq
+// typeHasNoAlg reports whether t does not have any associated hash/eq
 // algorithms because t, or some component of t, is marked Noalg.
 func typeHasNoAlg(t *types.Type) bool {
 	a, bad := algtype1(t)

src/cmd/compile/internal/mips/ssa.go

@@ -14,12 +14,12 @@ import (
 	"cmd/internal/obj/mips"
 )
 
-// isFPreg returns whether r is an FP register
+// isFPreg reports whether r is an FP register
 func isFPreg(r int16) bool {
 	return mips.REG_F0 <= r && r <= mips.REG_F31
 }
 
-// isHILO returns whether r is HI or LO register
+// isHILO reports whether r is HI or LO register
 func isHILO(r int16) bool {
 	return r == mips.REG_HI || r == mips.REG_LO
 }

src/cmd/compile/internal/mips64/ssa.go

@@ -14,12 +14,12 @@ import (
 	"cmd/internal/obj/mips"
 )
 
-// isFPreg returns whether r is an FP register
+// isFPreg reports whether r is an FP register
 func isFPreg(r int16) bool {
 	return mips.REG_F0 <= r && r <= mips.REG_F31
 }
 
-// isHILO returns whether r is HI or LO register
+// isHILO reports whether r is HI or LO register
 func isHILO(r int16) bool {
 	return r == mips.REG_HI || r == mips.REG_LO
 }

src/cmd/compile/internal/ssa/biasedsparsemap.go

@@ -43,7 +43,7 @@ func (s *biasedSparseMap) size() int {
 	return s.s.size()
 }
 
-// contains returns whether x is a key in s
+// contains reports whether x is a key in s
 func (s *biasedSparseMap) contains(x uint) bool {
 	if s.s == nil {
 		return false

src/cmd/compile/internal/ssa/config.go

@@ -164,7 +164,7 @@ type Frontend interface {
 	// given name.
 	Syslook(string) *obj.LSym
 
-	// UseWriteBarrier returns whether write barrier is enabled
+	// UseWriteBarrier reports whether write barrier is enabled
 	UseWriteBarrier() bool
 
 	// SetWBPos indicates that a write barrier has been inserted

src/cmd/compile/internal/ssa/magic.go

@@ -83,7 +83,7 @@ import "math/big"
 //                   a+b has n+1 bits in it.  Nevertheless, can be done
 //                   in 2 instructions on x86.)
 
-// umagicOK returns whether we should strength reduce a n-bit divide by c.
+// umagicOK reports whether we should strength reduce a n-bit divide by c.
 func umagicOK(n uint, c int64) bool {
 	// Convert from ConstX auxint values to the real uint64 constant they represent.
 	d := uint64(c) << (64 - n) >> (64 - n)

src/cmd/compile/internal/ssa/numberlines.go

@@ -20,7 +20,7 @@ func isPoorStatementOp(op Op) bool {
 	return false
 }
 
-// LosesStmtMark returns whether a prog with op as loses its statement mark on the way to DWARF.
+// LosesStmtMark reports whether a prog with op as loses its statement mark on the way to DWARF.
 // The attributes from some opcodes are lost in translation.
 // TODO: this is an artifact of how funcpctab combines information for instructions at a single PC.
 // Should try to fix it there.

src/cmd/compile/internal/ssa/rewrite.go

@@ -320,7 +320,7 @@ func canMergeLoad(target, load *Value) bool {
 	return true
 }
 
-// isSameSym returns whether sym is the same as the given named symbol
+// isSameSym reports whether sym is the same as the given named symbol
 func isSameSym(sym interface{}, name string) bool {
 	s, ok := sym.(fmt.Stringer)
 	return ok && s.String() == name

src/cmd/compile/internal/ssa/value.go

@@ -300,7 +300,7 @@ func (v *Value) Fatalf(msg string, args ...interface{}) {
 	v.Block.Func.fe.Fatalf(v.Pos, msg, args...)
 }
 
-// isGenericIntConst returns whether v is a generic integer constant.
+// isGenericIntConst reports whether v is a generic integer constant.
 func (v *Value) isGenericIntConst() bool {
 	return v != nil && (v.Op == OpConst64 || v.Op == OpConst32 || v.Op == OpConst16 || v.Op == OpConst8)
 }

src/cmd/compile/internal/ssa/writebarrier.go

@@ -11,7 +11,7 @@ import (
 	"strings"
 )
 
-// needwb returns whether we need write barrier for store op v.
+// needwb reports whether we need write barrier for store op v.
 // v must be Store/Move/Zero.
 func needwb(v *Value) bool {
 	t, ok := v.Aux.(*types.Type)

src/cmd/compile/internal/types/type.go

@@ -1457,7 +1457,7 @@ func Haspointers1(t *Type, ignoreNotInHeap bool) bool {
 	return true
 }
 
-// HasHeapPointer returns whether t contains a heap pointer.
+// HasHeapPointer reports whether t contains a heap pointer.
 // This is used for write barrier insertion, so it ignores
 // pointers to go:notinheap types.
 func (t *Type) HasHeapPointer() bool {

src/cmd/internal/obj/arm64/asm7.go

@@ -1183,7 +1183,7 @@ func isaddcon(v int64) bool {
 	return v <= 0xFFF
 }
 
-// isbitcon returns whether a constant can be encoded into a logical instruction.
+// isbitcon reports whether a constant can be encoded into a logical instruction.
 // bitcon has a binary form of repetition of a bit sequence of length 2, 4, 8, 16, 32, or 64,
 // which itself is a rotate (w.r.t. the length of the unit) of a sequence of ones.
 // special cases: 0 and -1 are not bitcon.

src/cmd/internal/objabi/reloctype.go

@@ -198,7 +198,7 @@ const (
 	R_WASMIMPORT
 )
 
-// IsDirectJump returns whether r is a relocation for a direct jump.
+// IsDirectJump reports whether r is a relocation for a direct jump.
 // A direct jump is a CALL or JMP instruction that takes the target address
 // as immediate. The address is embedded into the instruction, possibly
 // with limited width.

src/cmd/link/internal/ld/data.go

@@ -48,7 +48,7 @@ import (
 	"sync"
 )
 
-// isRuntimeDepPkg returns whether pkg is the runtime package or its dependency
+// isRuntimeDepPkg reports whether pkg is the runtime package or its dependency
 func isRuntimeDepPkg(pkg string) bool {
 	switch pkg {
 	case "runtime",

src/cmd/link/internal/ld/lib.go

@@ -158,7 +158,7 @@ const (
 	MINFUNC = 16 // minimum size for a function
 )
 
-// DynlinkingGo returns whether we are producing Go code that can live
+// DynlinkingGo reports whether we are producing Go code that can live
 // in separate shared libraries linked together at runtime.
 func (ctxt *Link) DynlinkingGo() bool {
 	if !ctxt.Loaded {
@@ -167,12 +167,12 @@ func (ctxt *Link) DynlinkingGo() bool {
 	return ctxt.BuildMode == BuildModeShared || ctxt.linkShared || ctxt.BuildMode == BuildModePlugin || ctxt.CanUsePlugins()
 }
 
-// CanUsePlugins returns whether a plugins can be used
+// CanUsePlugins reports whether a plugins can be used
 func (ctxt *Link) CanUsePlugins() bool {
 	return ctxt.Syms.ROLookup("plugin.Open", sym.SymVerABIInternal) != nil
 }
 
-// UseRelro returns whether to make use of "read only relocations" aka
+// UseRelro reports whether to make use of "read only relocations" aka
 // relro.
 func (ctxt *Link) UseRelro() bool {
 	switch ctxt.BuildMode {

src/cmd/pprof/readlineui.go

@@ -101,7 +101,7 @@ func colorize(msg string) string {
 	return colorEscape + msg + colorResetEscape
 }
 
-// IsTerminal returns whether the UI is known to be tied to an
+// IsTerminal reports whether the UI is known to be tied to an
 // interactive terminal (as opposed to being redirected to a file).
 func (r *readlineUI) IsTerminal() bool {
 	const stdout = 1

src/cmd/trace/annotations.go

@@ -538,7 +538,7 @@ func (task *taskDesc) overlappingInstant(ev *trace.Event) bool {
 	return false
 }
 
-// overlappingDuration returns whether the durational event, ev, overlaps with
+// overlappingDuration reports whether the durational event, ev, overlaps with
 // any of the task's region if ev is a goroutine-local event, or overlaps with
 // the task's lifetime if ev is a global event. It returns the overlapping time
 // as well.

src/crypto/tls/common.go

@@ -240,7 +240,7 @@ const (
 	RequireAndVerifyClientCert
 )
 
-// requiresClientCert returns whether the ClientAuthType requires a client
+// requiresClientCert reports whether the ClientAuthType requires a client
 // certificate to be provided.
 func requiresClientCert(c ClientAuthType) bool {
 	switch c {

src/crypto/tls/handshake_server_tls13.go

@@ -464,7 +464,7 @@ func (hs *serverHandshakeStateTLS13) doHelloRetryRequest(selectedGroup CurveID)
 	return nil
 }
 
-// illegalClientHelloChange returns whether the two ClientHello messages are
+// illegalClientHelloChange reports whether the two ClientHello messages are
 // different, with the exception of the changes allowed before and after a
 // HelloRetryRequest. See RFC 8446, Section 4.1.2.
 func illegalClientHelloChange(ch, ch1 *clientHelloMsg) bool {

src/crypto/x509/pkix/pkix.go

@@ -227,7 +227,7 @@ func (n Name) String() string {
 	return n.ToRDNSequence().String()
 }
 
-// oidInAttributeTypeAndValue returns whether a type with the given OID exists
+// oidInAttributeTypeAndValue reports whether a type with the given OID exists
 // in atv.
 func oidInAttributeTypeAndValue(oid asn1.ObjectIdentifier, atv []AttributeTypeAndValue) bool {
 	for _, a := range atv {

src/crypto/x509/verify.go

@@ -858,7 +858,7 @@ nextIntermediate:
 	return
 }
 
-// validHostname returns whether host is a valid hostname that can be matched or
+// validHostname reports whether host is a valid hostname that can be matched or
 // matched against according to RFC 6125 2.2, with some leniency to accommodate
 // legacy values.
 func validHostname(host string) bool {

src/crypto/x509/x509.go

@@ -1641,7 +1641,7 @@ var (
 	oidAuthorityInfoAccessIssuers = asn1.ObjectIdentifier{1, 3, 6, 1, 5, 5, 7, 48, 2}
 )
 
-// oidNotInExtensions returns whether an extension with the given oid exists in
+// oidNotInExtensions reports whether an extension with the given oid exists in
 // extensions.
 func oidInExtensions(oid asn1.ObjectIdentifier, extensions []pkix.Extension) bool {
 	for _, e := range extensions {

src/database/sql/sql.go

@@ -2821,7 +2821,7 @@ func (ci *ColumnType) ScanType() reflect.Type {
 	return ci.scanType
 }
 
-// Nullable returns whether the column may be null.
+// Nullable reports whether the column may be null.
 // If a driver does not support this property ok will be false.
 func (ci *ColumnType) Nullable() (nullable, ok bool) {
 	return ci.nullable, ci.hasNullable

src/debug/dwarf/line.go

@@ -590,7 +590,7 @@ func (r *LineReader) SeekPC(pc uint64, entry *LineEntry) error {
 	}
 }
 
-// pathIsAbs returns whether path is an absolute path (or "full path
+// pathIsAbs reports whether path is an absolute path (or "full path
 // name" in DWARF parlance). This is in "whatever form makes sense for
 // the host system", so this accepts both UNIX-style and DOS-style
 // absolute paths. We avoid the filepath package because we want this

src/go/printer/nodes.go

@@ -976,7 +976,7 @@ func (p *printer) possibleSelectorExpr(expr ast.Expr, prec1, depth int) bool {
 	return false
 }
 
-// selectorExpr handles an *ast.SelectorExpr node and returns whether x spans
+// selectorExpr handles an *ast.SelectorExpr node and reports whether x spans
 // multiple lines.
 func (p *printer) selectorExpr(x *ast.SelectorExpr, depth int, isMethod bool) bool {
 	p.expr1(x.X, token.HighestPrec, depth)

src/internal/goroot/gc.go

@@ -14,7 +14,7 @@ import (
 	"sync"
 )
 
-// IsStandardPackage returns whether path is a standard package,
+// IsStandardPackage reports whether path is a standard package,
 // given goroot and compiler.
 func IsStandardPackage(goroot, compiler, path string) bool {
 	switch compiler {
@@ -95,7 +95,7 @@ func (gd *gccgoDirs) init() {
 	gd.dirs = append(gd.dirs, lastDirs...)
 }
 
-// isStandard returns whether path is a standard library for gccgo.
+// isStandard reports whether path is a standard library for gccgo.
 func (gd *gccgoDirs) isStandard(path string) bool {
 	// Quick check: if the first path component has a '.', it's not
 	// in the standard library. This skips most GOPATH directories.

src/internal/goroot/gccgo.go

@@ -11,7 +11,7 @@ import (
 	"path/filepath"
 )
 
-// IsStandardPackage returns whether path is a standard package,
+// IsStandardPackage reports whether path is a standard package,
 // given goroot and compiler.
 func IsStandardPackage(goroot, compiler, path string) bool {
 	switch compiler {

src/net/http/cookie.go

@@ -263,7 +263,7 @@ func readCookies(h Header, filter string) []*Cookie {
 	return cookies
 }
 
-// validCookieDomain returns whether v is a valid cookie domain-value.
+// validCookieDomain reports whether v is a valid cookie domain-value.
 func validCookieDomain(v string) bool {
 	if isCookieDomainName(v) {
 		return true
@@ -274,13 +274,13 @@ func validCookieDomain(v string) bool {
 	return false
 }
 
-// validCookieExpires returns whether v is a valid cookie expires-value.
+// validCookieExpires reports whether v is a valid cookie expires-value.
 func validCookieExpires(t time.Time) bool {
 	// IETF RFC 6265 Section 5.1.1.5, the year must not be less than 1601
 	return t.Year() >= 1601
 }
 
-// isCookieDomainName returns whether s is a valid domain name or a valid
+// isCookieDomainName reports whether s is a valid domain name or a valid
 // domain name with a leading dot '.'.  It is almost a direct copy of
 // package net's isDomainName.
 func isCookieDomainName(s string) bool {

src/net/http/h2_bundle.go

@@ -3082,7 +3082,7 @@ func (srv *Server) ListenAndServeTLS(certFile, keyFile string) error {
 }
 
 // setupHTTP2_ServeTLS conditionally configures HTTP/2 on
-// srv and returns whether there was an error setting it up. If it is
+// srv and reports whether there was an error setting it up. If it is
 // not configured for policy reasons, nil is returned.
 func (srv *Server) setupHTTP2_ServeTLS() error {
 	srv.nextProtoOnce.Do(srv.onceSetNextProtoDefaults)