_content/doc/comment: mention "reports whether" idiom

Mention the idiom of using "reports whether" to describe functions
that return a boolean.

While here, replace several uses of "func" with "function". In the Go
spec, "func" is a keyword used in function declarations and function
literals, but the declared object is always referred to as a
"function".

Also, change "arguments" to "parameters". Again, in the Go spec,
"arguments" is used to describe the operands that appear in a call
expression, whereas "parameters" are the objects declared in a
function signature.

Change-Id: I01dfafd05af1852a8d2056bdabbda1e2bcc8cbb7
Reviewed-on: https://go-review.googlesource.com/c/website/+/524956
Reviewed-by: Rob Pike <r@golang.org>
Reviewed-by: Ian Lance Taylor <iant@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

_content/doc/comment.md

@@ -225,9 +225,9 @@ For example:
 
 ## Funcs {#func}
 
-A func's doc comment should explain what the function returns
+A function's doc comment should explain what the function returns
 or, for functions called for side effects, what it does.
-Named arguments or results can be referred to directly in
+Named parameters and results can be referred to directly in
 the comment, without any special syntax like backquotes.
 (A consequence of this convention is that names like `a`,
 which might be mistaken for ordinary words, are typically avoided.)
@@ -255,6 +255,16 @@ And:
 		...
 	}
 
+Doc comments typically use the phrase “reports whether”
+to describe functions that return a boolean.
+The phrase “or not” is unnecessary.
+For example:
+
+	package strings
+
+	// HasPrefix reports whether the string s begins with prefix.
+	func HasPrefix(s, prefix string) bool
+
 If a doc comment needs to explain multiple results,
 naming the results can make the doc comment more understandable,
 even if the names are not used in the body of the function.
@@ -306,7 +316,7 @@ perhaps with an additional error result,
 are shown alongside the type `T` and its methods,
 under the assumption that they are `T`'s constructors.
 
-By default, programmers can assume that a top-level func
+By default, programmers can assume that a top-level function
 is safe to call from multiple goroutines;
 this fact need not be stated explicitly.
 
@@ -330,7 +340,7 @@ For example:
 		...
 	}
 
-Note that func and method doc comments focus on
+Note that function and method doc comments focus on
 what the operation returns or does,
 detailing what the caller needs to know.
 Special cases can be particularly important to document.