mime/multipart: add NewReader example

Fixes #7888

LGTM=adg
R=adg
CC=golang-codereviews
https://golang.org/cl/100420043

src/pkg/mime/multipart/example_test.go

+// Copyright 2014 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package multipart_test
+
+import (
+	"fmt"
+	"io"
+	"io/ioutil"
+	"log"
+	"mime"
+	"mime/multipart"
+	"net/mail"
+	"strings"
+)
+
+func ExampleNewReader() {
+	msg := &mail.Message{
+		Header: map[string][]string{
+			"Content-Type": []string{"multipart/mixed; boundary=foo"},
+		},
+		Body: strings.NewReader(
+			"--foo\r\nFoo: one\r\n\r\nA section\r\n" +
+				"--foo\r\nFoo: two\r\n\r\nAnd another\r\n" +
+				"--foo--\r\n"),
+	}
+	mediaType, params, err := mime.ParseMediaType(msg.Header.Get("Content-Type"))
+	if err != nil {
+		log.Fatal(err)
+	}
+	if strings.HasPrefix(mediaType, "multipart/") {
+		mr := multipart.NewReader(msg.Body, params["boundary"])
+		for {
+			p, err := mr.NextPart()
+			if err == io.EOF {
+				return
+			}
+			if err != nil {
+				log.Fatal(err)
+			}
+			slurp, err := ioutil.ReadAll(p)
+			if err != nil {
+				log.Fatal(err)
+			}
+			fmt.Printf("Part %q: %q\n", p.Header.Get("Foo"), slurp)
+		}
+	}
+
+	// Output:
+	// Part "one": "A section"
+	// Part "two": "And another"
+}

src/pkg/mime/multipart/multipart.go

@@ -81,12 +81,16 @@ func (p *Part) parseContentDisposition() {
 	}
 }
 
-// NewReader creates a new multipart Reader reading from reader using the
+// NewReader creates a new multipart Reader reading from r using the
 // given MIME boundary.
-func NewReader(reader io.Reader, boundary string) *Reader {
+//
+// The boundary is usually obtained from the "boundary" parameter of
+// the message's "Content-Type" header. Use mime.ParseMediaType to
+// parse such headers.
+func NewReader(r io.Reader, boundary string) *Reader {
 	b := []byte("\r\n--" + boundary + "--")
 	return &Reader{
-		bufReader: bufio.NewReader(reader),
+		bufReader: bufio.NewReader(r),
 
 		nl:               b[:2],
 		nlDashBoundary:   b[:len(b)-2],