docs: remove some prose-unworthy empty parentheses.

In our evolving style, prose should name a function "f" not "f()".

R=gri, rsc
CC=golang-dev
https://golang.org/cl/4550075

doc/effective_go.html

@@ -935,13 +935,14 @@ example of its possibilities.
 
 <h2 id="data">Data</h2>
 
-<h3 id="allocation_new">Allocation with <code>new()</code></h3>
+<h3 id="allocation_new">Allocation with <code>new</code></h3>
 
 <p>
-Go has two allocation primitives, <code>new()</code> and <code>make()</code>.
+Go has two allocation primitives, the built-in functions
+<code>new</code> and <code>make</code>.
 They do different things and apply to different types, which can be confusing,
 but the rules are simple.
-Let's talk about <code>new()</code> first.
+Let's talk about <code>new</code> first.
 It's a built-in function essentially the same as its namesakes
 in other languages: <code>new(T)</code> allocates zeroed storage for a new item of type
 <code>T</code> and returns its address, a value of type <code>*T</code>.
@@ -950,9 +951,9 @@ In Go terminology, it returns a pointer to a newly allocated zero value of type
 </p>
 
 <p>
-Since the memory returned by <code>new()</code> is zeroed, it's helpful to arrange that the
+Since the memory returned by <code>new</code> is zeroed, it's helpful to arrange that the
 zeroed object can be used without further initialization.  This means a user of
-the data structure can create one with <code>new()</code> and get right to
+the data structure can create one with <code>new</code> and get right to
 work.
 For example, the documentation for <code>bytes.Buffer</code> states that
 "the zero value for <code>Buffer</code> is an empty buffer ready to use."
@@ -1065,7 +1066,7 @@ s := []string      {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
 m := map[int]string{Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
 </pre>
 
-<h3 id="allocation_make">Allocation with <code>make()</code></h3>
+<h3 id="allocation_make">Allocation with <code>make</code></h3>
 
 <p>
 Back to allocation.
@@ -1099,8 +1100,8 @@ In contrast, <code>new([]int)</code> returns a pointer to a newly allocated, zer
 structure, that is, a pointer to a <code>nil</code> slice value.
 
 <p>
-These examples illustrate the difference between <code>new()</code> and
-<code>make()</code>.
+These examples illustrate the difference between <code>new</code> and
+<code>make</code>.
 </p>
 
 <pre>
@@ -1116,9 +1117,9 @@ v := make([]int, 100)
 </pre>
 
 <p>
-Remember that <code>make()</code> applies only to maps, slices and channels
+Remember that <code>make</code> applies only to maps, slices and channels
 and does not return a pointer.
-To obtain an explicit pointer allocate with <code>new()</code>.
+To obtain an explicit pointer allocate with <code>new</code>.
 </p>
 
 <h3 id="arrays">Arrays</h3>
@@ -1473,7 +1474,7 @@ map[string] int
 </pre>
 <p>
 If you want to control the default format for a custom type, all that's required is to define
-a method <code>String() string</code> on the type.
+a method with the signature <code>String() string</code> on the type.
 For our simple type <code>T</code>, that might look like this.
 </p>
 <pre>
@@ -1495,7 +1496,7 @@ that's more efficient and idiomatic for struct types.
 See the section below on <a href="#pointers_vs_values">pointers vs. value receivers</a> for more information.)
 </p>
 <p>
-Our <code>String()</code> method is able to call <code>Sprintf</code> because the
+Our <code>String</code> method is able to call <code>Sprintf</code> because the
 print routines are fully reentrant and can be used recursively.
 We can even go one step further and pass a print routine's arguments directly to another such routine.
 The signature of <code>Printf</code> uses the type <code>...interface{}</code>
@@ -1683,19 +1684,20 @@ var (
 <h3 id="init">The init function</h3>
 
 <p>
-Finally, each source file can define its own <code>init()</code> function to
-set up whatever state is required.  The only restriction is that, although
+Finally, each source file can define its own niladic <code>init</code> function to
+set up whatever state is required.  (Actually each file can have multiple
+<code>init</code> functions.) The only restriction is that, although
 goroutines can be launched during initialization, they will not begin
 execution until it completes; initialization always runs as a single thread
 of execution.
-And finally means finally: <code>init()</code> is called after all the
+And finally means finally: <code>init</code> is called after all the
 variable declarations in the package have evaluated their initializers,
 and those are evaluated only after all the imported packages have been
 initialized.
 </p>
 <p>
 Besides initializations that cannot be expressed as declarations,
-a common use of <code>init()</code> functions is to verify or repair
+a common use of <code>init</code> functions is to verify or repair
 correctness of the program state before real execution begins.
 </p>
 
@@ -1899,7 +1901,7 @@ on every instance of a common method.
 In such cases, the constructor should return an interface value
 rather than the implementing type.
 As an example, in the hash libraries
-both <code>crc32.NewIEEE()</code> and <code>adler32.New()</code>
+both <code>crc32.NewIEEE</code> and <code>adler32.New</code>
 return the interface type <code>hash.Hash32</code>.
 Substituting the CRC-32 algorithm for Adler-32 in a Go program
 requires only changing the constructor call;

doc/go_spec.html

 <!-- title The Go Programming Language Specification -->
-<!-- subtitle Version of May 23, 2011 -->
+<!-- subtitle Version of May 24, 2011 -->
 
 <!--
 TODO
@@ -821,7 +821,7 @@ make([]T, length, capacity)
 </pre>
 
 <p>
-The <code>make()</code> call allocates a new, hidden array to which the returned
+A call to <code>make</code> allocates a new, hidden array to which the returned
 slice value refers. That is, executing
 </p>
 
@@ -4931,7 +4931,7 @@ func main() {
 <h3 id="The_zero_value">The zero value</h3>
 <p>
 When memory is allocated to store a value, either through a declaration
-or <code>make()</code> or <code>new()</code> call,
+or a call of <code>make</code> or <code>new</code>,
 and no explicit initialization is provided, the memory is
 given a default initialization.  Each element of such a value is
 set to the <i>zero value</i> for its type: <code>false</code> for booleans,
@@ -4989,7 +4989,7 @@ func init()
 <p>
 defined in its source.
 A package may contain multiple
-<code>init()</code> functions, even
+<code>init</code> functions, even
 within a single source file; they execute
 in unspecified order.
 </p>
@@ -5019,8 +5019,8 @@ program is complete. Therefore, all initialization code is run in a single
 goroutine.
 </p>
 <p>
-An <code>init()</code> function cannot be referred to from anywhere
-in a program. In particular, <code>init()</code> cannot be called explicitly,
+An <code>init</code> function cannot be referred to from anywhere
+in a program. In particular, <code>init</code> cannot be called explicitly,
 nor can a pointer to <code>init</code> be assigned to a function variable.
 </p>
 <p>

doc/go_tutorial.html

@@ -341,7 +341,7 @@ Using slices one can write this function (from <code>sum.go</code>):
 15    }
 </pre>
 <p>
-Note how the return type (<code>int</code>) is defined for <code>sum()</code> by stating it
+Note how the return type (<code>int</code>) is defined for <code>sum</code> by stating it
 after the parameter list.
 <p>
 To call the function, we slice the array.  This intricate call (we'll show
@@ -373,7 +373,7 @@ There are also maps, which you can initialize like this:
     m := map[string]int{"one":1 , "two":2}
 </pre>
 <p>
-The built-in function <code>len()</code>, which returns number of elements,
+The built-in function <code>len</code>, which returns number of elements,
 makes its first appearance in <code>sum</code>.  It works on strings, arrays,
 slices, maps, and channels.
 <p>
@@ -401,7 +401,7 @@ for more examples of its use.
 Most types in Go are values. If you have an <code>int</code> or a <code>struct</code>
 or an array, assignment
 copies the contents of the object.
-To allocate a new variable, use <code>new()</code>, which
+To allocate a new variable, use the built-in function <code>new</code>, which
 returns a pointer to the allocated storage.
 <p>
 <pre>
@@ -418,7 +418,7 @@ or the more idiomatic
 Some types&mdash;maps, slices, and channels (see below)&mdash;have reference semantics.
 If you're holding a slice or a map and you modify its contents, other variables
 referencing the same underlying data will see the modification.  For these three
-types you want to use the built-in function <code>make()</code>:
+types you want to use the built-in function <code>make</code>:
 <p>
 <pre>
     m := make(map[string]int)
@@ -432,11 +432,11 @@ If you just declare the map, as in
 </pre>
 <p>
 it creates a <code>nil</code> reference that cannot hold anything. To use the map,
-you must first initialize the reference using <code>make()</code> or by assignment from an
+you must first initialize the reference using <code>make</code> or by assignment from an
 existing map.
 <p>
 Note that <code>new(T)</code> returns type <code>*T</code> while <code>make(T)</code> returns type
-<code>T</code>.  If you (mistakenly) allocate a reference object with <code>new()</code>,
+<code>T</code>.  If you (mistakenly) allocate a reference object with <code>new</code> rather than <code>make</code>,
 you receive a pointer to a nil reference, equivalent to
 declaring an uninitialized variable and taking its address.
 <p>
@@ -767,7 +767,7 @@ Building on the <code>file</code> package, here's a simple version of the Unix u
 By now this should be easy to follow, but the <code>switch</code> statement introduces some
 new features.  Like a <code>for</code> loop, an <code>if</code> or <code>switch</code> can include an
 initialization statement.  The <code>switch</code> on line 18 uses one to create variables
-<code>nr</code> and <code>er</code> to hold the return values from <code>f.Read()</code>.  (The <code>if</code> on line 25
+<code>nr</code> and <code>er</code> to hold the return values from the call to <code>f.Read</code>.  (The <code>if</code> on line 25
 has the same idea.)  The <code>switch</code> statement is general: it evaluates the cases
 from  top to bottom looking for the first case that matches the value; the
 case expressions don't need to be constants or even integers, as long as
@@ -779,14 +779,14 @@ in a <code>for</code> statement, a missing value means <code>true</code>.  In fa
 is a form of <code>if-else</code> chain. While we're here, it should be mentioned that in
 <code>switch</code> statements each <code>case</code> has an implicit <code>break</code>.
 <p>
-Line 25 calls <code>Write()</code> by slicing the incoming buffer, which is itself a slice.
+Line 25 calls <code>Write</code> by slicing the incoming buffer, which is itself a slice.
 Slices provide the standard Go way to handle I/O buffers.
 <p>
 Now let's make a variant of <code>cat</code> that optionally does <code>rot13</code> on its input.
 It's easy to do by just processing the bytes, but instead we will exploit
 Go's notion of an <i>interface</i>.
 <p>
-The <code>cat()</code> subroutine uses only two methods of <code>f</code>: <code>Read()</code> and <code>String()</code>,
+The <code>cat</code> subroutine uses only two methods of <code>f</code>: <code>Read</code> and <code>String</code>,
 so let's start by defining an interface that has exactly those two methods.
 Here is code from <code>progs/cat_rot13.go</code>:
 <p>
@@ -838,7 +838,7 @@ To use the new feature, we define a flag:
 14    var rot13Flag = flag.Bool(&quot;rot13&quot;, false, &quot;rot13 the input&quot;)
 </pre>
 <p>
-and use it from within a mostly unchanged <code>cat()</code> function:
+and use it from within a mostly unchanged <code>cat</code> function:
 <p>
 <pre> <!-- progs/cat_rot13.go /func.cat/ /^}/ -->
 52    func cat(r reader) {
@@ -866,7 +866,7 @@ and use it from within a mostly unchanged <code>cat()</code> function:
 74    }
 </pre>
 <p>
-(We could also do the wrapping in <code>main</code> and leave <code>cat()</code> mostly alone, except
+(We could also do the wrapping in <code>main</code> and leave <code>cat</code> mostly alone, except
 for changing the type of the argument; consider that an exercise.)
 Lines 56 through 58 set it all up: If the <code>rot13</code> flag is true, wrap the <code>reader</code>
 we received into a <code>rotate13</code> and proceed.  Note that the interface variables
@@ -1055,7 +1055,7 @@ to that of the <code>Printf</code> call above.
 </pre>
 <p>
 If you have your own type you'd like <code>Printf</code> or <code>Print</code> to format,
-just give it a <code>String()</code> method that returns a string.  The print
+just give it a <code>String</code> method that returns a string.  The print
 routines will examine the value to inquire whether it implements
 the method and if so, use it rather than some other formatting.
 Here's a simple example.
@@ -1076,14 +1076,14 @@ Here's a simple example.
 21    }
 </pre>
 <p>
-Since <code>*testType</code> has a <code>String()</code> method, the
+Since <code>*testType</code> has a <code>String</code> method, the
 default formatter for that type will use it and produce the output
 <p>
 <pre>
     77 Sunset Strip
 </pre>
 <p>
-Observe that the <code>String()</code> method calls <code>Sprint</code> (the obvious Go
+Observe that the <code>String</code> method calls <code>Sprint</code> (the obvious Go
 variant that returns a string) to do its formatting; special formatters
 can use the <code>fmt</code> library recursively.
 <p>
@@ -1096,7 +1096,7 @@ and such, but that's getting a little off the main thread so we'll leave it
 as an exploration exercise.
 <p>
 You might ask, though, how <code>Printf</code> can tell whether a type implements
-the <code>String()</code> method.  Actually what it does is ask if the value can
+the <code>String</code> method.  Actually what it does is ask if the value can
 be converted to an interface variable that implements the method.
 Schematically, given a value <code>v</code>, it does this:
 <p>
@@ -1141,7 +1141,7 @@ interface type defined in the <code>io</code> library:
 <p>
 (This interface is another conventional name, this time for <code>Write</code>; there are also
 <code>io.Reader</code>, <code>io.ReadWriter</code>, and so on.)
-Thus you can call <code>Fprintf</code> on any type that implements a standard <code>Write()</code>
+Thus you can call <code>Fprintf</code> on any type that implements a standard <code>Write</code>
 method, not just files but also network channels, buffers, whatever
 you want.
 <p>

doc/go_tutorial.txt

@@ -272,7 +272,7 @@ Using slices one can write this function (from "sum.go"):
 
 --PROG progs/sum.go /sum/ /^}/
 
-Note how the return type ("int") is defined for "sum()" by stating it
+Note how the return type ("int") is defined for "sum" by stating it
 after the parameter list.
 
 To call the function, we slice the array.  This intricate call (we'll show
@@ -296,7 +296,7 @@ There are also maps, which you can initialize like this:
 
 	m := map[string]int{"one":1 , "two":2}
 
-The built-in function "len()", which returns number of elements,
+The built-in function "len", which returns number of elements,
 makes its first appearance in "sum".  It works on strings, arrays,
 slices, maps, and channels.
 
@@ -321,7 +321,7 @@ An Interlude about Allocation
 Most types in Go are values. If you have an "int" or a "struct"
 or an array, assignment
 copies the contents of the object.
-To allocate a new variable, use "new()", which
+To allocate a new variable, use the built-in function "new", which
 returns a pointer to the allocated storage.
 
 	type T struct { a, b int }
@@ -334,7 +334,7 @@ or the more idiomatic
 Some types—maps, slices, and channels (see below)—have reference semantics.
 If you're holding a slice or a map and you modify its contents, other variables
 referencing the same underlying data will see the modification.  For these three
-types you want to use the built-in function "make()":
+types you want to use the built-in function "make":
 
 	m := make(map[string]int)
 
@@ -344,11 +344,11 @@ If you just declare the map, as in
 	var m map[string]int
 
 it creates a "nil" reference that cannot hold anything. To use the map,
-you must first initialize the reference using "make()" or by assignment from an
+you must first initialize the reference using "make" or by assignment from an
 existing map.
 
 Note that "new(T)" returns type "*T" while "make(T)" returns type
-"T".  If you (mistakenly) allocate a reference object with "new()",
+"T".  If you (mistakenly) allocate a reference object with "new" rather than "make",
 you receive a pointer to a nil reference, equivalent to
 declaring an uninitialized variable and taking its address.
 
@@ -526,7 +526,7 @@ Building on the "file" package, here's a simple version of the Unix utility "cat
 By now this should be easy to follow, but the "switch" statement introduces some
 new features.  Like a "for" loop, an "if" or "switch" can include an
 initialization statement.  The "switch" on line 18 uses one to create variables
-"nr" and "er" to hold the return values from "f.Read()".  (The "if" on line 25
+"nr" and "er" to hold the return values from the call to "f.Read".  (The "if" on line 25
 has the same idea.)  The "switch" statement is general: it evaluates the cases
 from  top to bottom looking for the first case that matches the value; the
 case expressions don't need to be constants or even integers, as long as
@@ -538,14 +538,14 @@ in a "for" statement, a missing value means "true".  In fact, such a "switch"
 is a form of "if-else" chain. While we're here, it should be mentioned that in
 "switch" statements each "case" has an implicit "break".
 
-Line 25 calls "Write()" by slicing the incoming buffer, which is itself a slice.
+Line 25 calls "Write" by slicing the incoming buffer, which is itself a slice.
 Slices provide the standard Go way to handle I/O buffers.
 
 Now let's make a variant of "cat" that optionally does "rot13" on its input.
 It's easy to do by just processing the bytes, but instead we will exploit
 Go's notion of an <i>interface</i>.
 
-The "cat()" subroutine uses only two methods of "f": "Read()" and "String()",
+The "cat" subroutine uses only two methods of "f": "Read" and "String",
 so let's start by defining an interface that has exactly those two methods.
 Here is code from "progs/cat_rot13.go":
 
@@ -569,11 +569,11 @@ To use the new feature, we define a flag:
 
 --PROG progs/cat_rot13.go /rot13Flag/
 
-and use it from within a mostly unchanged "cat()" function:
+and use it from within a mostly unchanged "cat" function:
 
 --PROG progs/cat_rot13.go /func.cat/ /^}/
 
-(We could also do the wrapping in "main" and leave "cat()" mostly alone, except
+(We could also do the wrapping in "main" and leave "cat" mostly alone, except
 for changing the type of the argument; consider that an exercise.)
 Lines 56 through 58 set it all up: If the "rot13" flag is true, wrap the "reader"
 we received into a "rotate13" and proceed.  Note that the interface variables
@@ -701,19 +701,19 @@ to that of the "Printf" call above.
 --PROG progs/print.go 'NR==21' 'NR==22'
 
 If you have your own type you'd like "Printf" or "Print" to format,
-just give it a "String()" method that returns a string.  The print
+just give it a "String" method that returns a string.  The print
 routines will examine the value to inquire whether it implements
 the method and if so, use it rather than some other formatting.
 Here's a simple example.
 
 --PROG progs/print_string.go 'NR==9' END
 
-Since "*testType" has a "String()" method, the
+Since "*testType" has a "String" method, the
 default formatter for that type will use it and produce the output
 
 	77 Sunset Strip
 
-Observe that the "String()" method calls "Sprint" (the obvious Go
+Observe that the "String" method calls "Sprint" (the obvious Go
 variant that returns a string) to do its formatting; special formatters
 can use the "fmt" library recursively.
 
@@ -726,7 +726,7 @@ and such, but that's getting a little off the main thread so we'll leave it
 as an exploration exercise.
 
 You might ask, though, how "Printf" can tell whether a type implements
-the "String()" method.  Actually what it does is ask if the value can
+the "String" method.  Actually what it does is ask if the value can
 be converted to an interface variable that implements the method.
 Schematically, given a value "v", it does this:
 
@@ -765,7 +765,7 @@ interface type defined in the "io" library:
 
 (This interface is another conventional name, this time for "Write"; there are also
 "io.Reader", "io.ReadWriter", and so on.)
-Thus you can call "Fprintf" on any type that implements a standard "Write()"
+Thus you can call "Fprintf" on any type that implements a standard "Write"
 method, not just files but also network channels, buffers, whatever
 you want.