encoding/pem: add Encode, EncodeToMemory docs

Included in a warning that EncodeToMemory may return an incomplete PEM
encoded structure if invalid headers are supplied. Example:

	pem.EncodeToMemory(&pem.Block{
		Headers: map[string]string{
			"a":   "test1",
			"b:c": "test2",
		},
	})

Returns:

	-----BEGIN -----
	a: test1

Change-Id: Ia9cf0202f985e3cf210aabb6f07667e581ff081f
Reviewed-on: https://go-review.googlesource.com/77790Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

src/encoding/pem/pem.go

@@ -252,6 +252,7 @@ func writeHeader(out io.Writer, k, v string) error {
 	return err
 }
 
+// Encode writes the Block b to out.
 func Encode(out io.Writer, b *Block) error {
 	if _, err := out.Write(pemStart[1:]); err != nil {
 		return err
@@ -310,6 +311,10 @@ func Encode(out io.Writer, b *Block) error {
 	return err
 }
 
+// EncodeToMemory returns the Block b.
+//
+// EncodeToMemory will return an incomplete PEM encoded structure if an invalid block is given.
+// To catch errors, Blocks with user-supplied headers should use Encode.
 func EncodeToMemory(b *Block) []byte {
 	var buf bytes.Buffer
 	Encode(&buf, b)