Add region tags to the Go protobuf examples.

This will allow us to like to specific snippets of code in the
documentation.  I plan to create a tutorial similar to the C# tutorial
https://developers.google.com/protocol-buffers/docs/csharptutorial

Since that tutorial has sections for populating a proto, parsing, and
serializing, I made a region for each of these for Go.  To make the
populating sample more self-contained, I refactor the listing example
slightly.

examples/add_person.go

@@ -105,7 +105,10 @@ func main() {
 			log.Fatalln("Error reading file:", err)
 		}
 	}
+
+	// [START marshal_proto]
 	book := &pb.AddressBook{}
+	// [START_EXCLUDE]
 	if err := proto.Unmarshal(in, book); err != nil {
 		log.Fatalln("Failed to parse address book:", err)
 	}
@@ -116,6 +119,7 @@ func main() {
 		log.Fatalln("Error with address:", err)
 	}
 	book.People = append(book.People, addr)
+	// [END_EXCLUDE]
 
 	// Write the new address book back to disk.
 	out, err := proto.Marshal(book)
@@ -125,4 +129,5 @@ func main() {
 	if err := ioutil.WriteFile(fname, out, 0644); err != nil {
 		log.Fatalln("Failed to write address book:", err)
 	}
+	// [END marshal_proto]
 }

examples/list_people.go

@@ -11,25 +11,29 @@ import (
 	pb "github.com/google/protobuf/examples/tutorial"
 )
 
-func listPeople(w io.Writer, book *pb.AddressBook) {
+func writePerson(w io.Writer, p *pb.Person) {
-	for _, p := range book.People {
+	fmt.Fprintln(w, "Person ID:", p.Id)
-		fmt.Fprintln(w, "Person ID:", p.Id)
+	fmt.Fprintln(w, "  Name:", p.Name)
-		fmt.Fprintln(w, "  Name:", p.Name)
+	if p.Email != "" {
-		if p.Email != "" {
+		fmt.Fprintln(w, "  E-mail address:", p.Email)
-			fmt.Fprintln(w, "  E-mail address:", p.Email)
+	}
-		}
 
-		for _, pn := range p.Phones {
+	for _, pn := range p.Phones {
-			switch pn.Type {
+		switch pn.Type {
-			case pb.Person_MOBILE:
+		case pb.Person_MOBILE:
-				fmt.Fprint(w, "  Mobile phone #: ")
+			fmt.Fprint(w, "  Mobile phone #: ")
-			case pb.Person_HOME:
+		case pb.Person_HOME:
-				fmt.Fprint(w, "  Home phone #: ")
+			fmt.Fprint(w, "  Home phone #: ")
-			case pb.Person_WORK:
+		case pb.Person_WORK:
-				fmt.Fprint(w, "  Work phone #: ")
+			fmt.Fprint(w, "  Work phone #: ")
-			}
-			fmt.Fprintln(w, pn.Number)
 		}
+		fmt.Fprintln(w, pn.Number)
+	}
+}
+
+func listPeople(w io.Writer, book *pb.AddressBook) {
+	for _, p := range book.People {
+		writePerson(w, p)
 	}
 }
 
@@ -41,19 +45,17 @@ func main() {
 	}
 	fname := os.Args[1]
 
+	// [START unmarshal_proto]
 	// Read the existing address book.
 	in, err := ioutil.ReadFile(fname)
 	if err != nil {
-		if os.IsNotExist(err) {
+		log.Fatalln("Error reading file:", err)
-			fmt.Printf("%s: File not found.  Creating new file.\n", fname)
-		} else {
-			log.Fatalln("Error reading file:", err)
-		}
 	}
 	book := &pb.AddressBook{}
 	if err := proto.Unmarshal(in, book); err != nil {
 		log.Fatalln("Failed to parse address book:", err)
 	}
+	// [END unmarshal_proto]
 
 	listPeople(os.Stdout, book)
 }

examples/list_people_test.go

@@ -8,6 +8,50 @@ import (
 	pb "github.com/google/protobuf/examples/tutorial"
 )
 
+func TestWritePersonWritesPerson(t *testing.T) {
+	buf := new(bytes.Buffer)
+	// [START populate_proto]
+	p := pb.Person{
+		Id:    1234,
+		Name:  "John Doe",
+		Email: "jdoe@example.com",
+		Phones: []*pb.Person_PhoneNumber{
+			{Number: "555-4321", Type: pb.Person_HOME},
+		},
+	}
+	// [END populate_proto]
+	writePerson(buf, &p)
+	want := strings.Split(`Person ID: 1234
+  Name: John Doe
+  E-mail address: jdoe@example.com
+  Home phone #: 555-4321
+`, "\n")
+
+	got := strings.Split(buf.String(), "\n")
+	if len(got) != len(want) {
+		t.Errorf(
+			"writePerson(%s) =>\n\t%q has %d lines, want %d",
+			p.String(),
+			buf.String(),
+			len(got),
+			len(want))
+	}
+	lines := len(got)
+	if lines > len(want) {
+		lines = len(want)
+	}
+	for i := 0; i < lines; i++ {
+		if got[i] != want[i] {
+			t.Errorf(
+				"writePerson(%s) =>\n\tline %d %q, want %q",
+				p.String(),
+				i,
+				got[i],
+				want[i])
+		}
+	}
+}
+
 func TestListPeopleWritesList(t *testing.T) {
 	buf := new(bytes.Buffer)
 	in := pb.AddressBook{[]*pb.Person{