archive/zip: add docs on type of slashes in paths

Fixes #5307

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/8676046

src/pkg/archive/zip/struct.go

@@ -64,8 +64,15 @@ const (
 	zip64ExtraId = 0x0001 // zip64 Extended Information Extra Field
 )
 
+// FileHeader describes a file within a zip file.
+// See the zip spec for details.
 type FileHeader struct {
-	Name               string
+	// Name is the name of the file.
+	// It must be a relative path: it must not start with a drive
+	// letter (e.g. C:) or leading slash, and only forward slashes
+	// are allowed.
+	Name string
+
 	CreatorVersion     uint16
 	ReaderVersion      uint16
 	Flags              uint16

src/pkg/archive/zip/writer.go

@@ -163,6 +163,9 @@ func (w *Writer) Close() error {
 
 // Create adds a file to the zip file using the provided name.
 // It returns a Writer to which the file contents should be written.
+// The name must be a relative path: it must not start with a drive
+// letter (e.g. C:) or leading slash, and only forward slashes are
+// allowed.
 // The file's contents must be written to the io.Writer before the next
 // call to Create, CreateHeader, or Close.
 func (w *Writer) Create(name string) (io.Writer, error) {