archive/tar: Add reader and writer code example.

Remove the previous comment examples.

R=golang-dev, minux.ma, adg
CC=golang-dev
https://golang.org/cl/7220048

src/pkg/archive/tar/example_test.go

+package tar_test
+
+import (
+	"archive/tar"
+	"bytes"
+	"fmt"
+	"io"
+	"log"
+	"os"
+)
+
+func Example() {
+	// Create a buffer to write our archive to.
+	buf := new(bytes.Buffer)
+
+	// Create a new tar archive.
+	tw := tar.NewWriter(buf)
+
+	// Add some files to the archive.
+	var files = []struct {
+		Name, Body string
+	}{
+		{"readme.txt", "This archive contains some text files."},
+		{"gopher.txt", "Gopher names:\nGeorge\nGeoffrey\nGonzo"},
+		{"todo.txt", "Get animal handling licence."},
+	}
+	for _, file := range files {
+		hdr := &tar.Header{
+			Name: file.Name,
+			Size: int64(len(file.Body)),
+		}
+		if err := tw.WriteHeader(hdr); err != nil {
+			log.Fatalln(err)
+		}
+		if _, err := tw.Write([]byte(file.Body)); err != nil {
+			log.Fatalln(err)
+		}
+	}
+	// Make sure to check the error on Close.
+	if err := tw.Close(); err != nil {
+		log.Fatalln(err)
+	}
+
+	// Open the tar archive for reading.
+	r := bytes.NewReader(buf.Bytes())
+	tr := tar.NewReader(r)
+
+	// Iterate through the files in the archive.
+	for {
+		hdr, err := tr.Next()
+		if err == io.EOF {
+			// end of tar archive
+			break
+		}
+		if err != nil {
+			log.Fatalln(err)
+		}
+		fmt.Printf("Contents of %s:\n", hdr.Name)
+		if _, err := io.Copy(os.Stdout, tr); err != nil {
+			log.Fatalln(err)
+		}
+		fmt.Println()
+	}
+
+	// Output:
+	// Contents of readme.txt:
+	// This archive contains some text files.
+	// Contents of gopher.txt:
+	// Gopher names:
+	// George
+	// Geoffrey
+	// Gonzo
+	// Contents of todo.txt:
+	// Get animal handling licence.
+}

src/pkg/archive/tar/reader.go

@@ -25,20 +25,6 @@ var (
 // A tar archive consists of a sequence of files.
 // The Next method advances to the next file in the archive (including the first),
 // and then it can be treated as an io.Reader to access the file's data.
-//
-// Example:
-//	tr := tar.NewReader(r)
-//	for {
-//		hdr, err := tr.Next()
-//		if err == io.EOF {
-//			// end of tar archive
-//			break
-//		}
-//		if err != nil {
-//			// handle error
-//		}
-//		io.Copy(data, tr)
-//	}
 type Reader struct {
 	r   io.Reader
 	err error

src/pkg/archive/tar/writer.go

@@ -25,17 +25,6 @@ var (
 // A tar archive consists of a sequence of files.
 // Call WriteHeader to begin a new file, and then call Write to supply that file's data,
 // writing at most hdr.Size bytes in total.
-//
-// Example:
-//	tw := tar.NewWriter(w)
-//	hdr := new(tar.Header)
-//	hdr.Size = length of data in bytes
-//	// populate other hdr fields as desired
-//	if err := tw.WriteHeader(hdr); err != nil {
-//		// handle error
-//	}
-//	io.Copy(tw, data)
-//	tw.Close()
 type Writer struct {
 	w          io.Writer
 	err        error