From 46f482a2fc9db18b0ffedafc844b1796bc11a5fa Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Wed, 25 May 2011 06:44:09 +1000 Subject: [PATCH] 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 | 36 +++++++++++++++++++----------------- doc/go_spec.html | 12 ++++++------ doc/go_tutorial.html | 32 ++++++++++++++++---------------- doc/go_tutorial.txt | 32 ++++++++++++++++---------------- 4 files changed, 57 insertions(+), 55 deletions(-) diff --git a/doc/effective_go.html b/doc/effective_go.html index 86b2d63dcba..f713b3edb87 100644 --- a/doc/effective_go.html +++ b/doc/effective_go.html @@ -935,13 +935,14 @@ example of its possibilities.

Data

-

Allocation with new()

+

Allocation with new

-Go has two allocation primitives, new() and make(). +Go has two allocation primitives, the built-in functions +new and make. They do different things and apply to different types, which can be confusing, but the rules are simple. -Let's talk about new() first. +Let's talk about new first. It's a built-in function essentially the same as its namesakes in other languages: new(T) allocates zeroed storage for a new item of type T and returns its address, a value of type *T. @@ -950,9 +951,9 @@ In Go terminology, it returns a pointer to a newly allocated zero value of type

-Since the memory returned by new() is zeroed, it's helpful to arrange that the +Since the memory returned by new 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 new() and get right to +the data structure can create one with new and get right to work. For example, the documentation for bytes.Buffer states that "the zero value for Buffer 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"} -

Allocation with make()

+

Allocation with make

Back to allocation. @@ -1099,8 +1100,8 @@ In contrast, new([]int) returns a pointer to a newly allocated, zer structure, that is, a pointer to a nil slice value.

-These examples illustrate the difference between new() and -make(). +These examples illustrate the difference between new and +make. 

@@ -1116,9 +1117,9 @@ v := make([]int, 100)

-Remember that make() applies only to maps, slices and channels +Remember that make applies only to maps, slices and channels and does not return a pointer. -To obtain an explicit pointer allocate with new(). +To obtain an explicit pointer allocate with new.

Arrays

@@ -1473,7 +1474,7 @@ map[string] int

If you want to control the default format for a custom type, all that's required is to define -a method String() string on the type. +a method with the signature String() string on the type. For our simple type T, that might look like this. 

@@ -1495,7 +1496,7 @@ that's more efficient and idiomatic for struct types.
 See the section below on pointers vs. value receivers for more information.)
 

 

-Our String() method is able to call Sprintf because the
+Our String method is able to call Sprintf 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 Printf uses the type ...interface{}
@@ -1683,19 +1684,20 @@ var (
 
The init function

 
 

-Finally, each source file can define its own init() function to
-set up whatever state is required.  The only restriction is that, although
+Finally, each source file can define its own niladic init function to
+set up whatever state is required.  (Actually each file can have multiple
+init 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: init() is called after all the
+And finally means finally: init 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.
 

 

 Besides initializations that cannot be expressed as declarations,
-a common use of init() functions is to verify or repair
+a common use of init functions is to verify or repair
 correctness of the program state before real execution begins.
 

 
@@ -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 crc32.NewIEEE() and adler32.New()
+both crc32.NewIEEE and adler32.New
 return the interface type hash.Hash32.
 Substituting the CRC-32 algorithm for Adler-32 in a Go program
 requires only changing the constructor call;
diff --git a/doc/go_spec.html b/doc/go_spec.html
index 13af1d83a13..a561bbdd0df 100644
--- a/doc/go_spec.html
+++ b/doc/go_spec.html
@@ -1,5 +1,5 @@
 
-
+
 
 
 52    func cat(r reader) {
@@ -866,7 +866,7 @@ and use it from within a mostly unchanged cat() function:
 74    }

-(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 @@ -1055,7 +1055,7 @@ to that of the Printf call above.

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. @@ -1076,14 +1076,14 @@ Here's a simple example. 21 }

-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.

@@ -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.

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:

@@ -1141,7 +1141,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.

diff --git a/doc/go_tutorial.txt b/doc/go_tutorial.txt index ab02baf2cd0..ebf58eca6c4 100644 --- a/doc/go_tutorial.txt +++ b/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 interface. -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.