encoding/hex: implement examples using all exported functions

Fixes #11254.
Updates #16360.

Implements examples using all exported functions.

This CL also updates Decode documentation to
state that only hexadecimal characters are accepted
in the source slice src, but also that the length
of src must be even.

Change-Id: Id016a4ba814f940cd300f26581fb4b9d2aded306
Reviewed-on: https://go-review.googlesource.com/28482
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>

src/encoding/hex/example_test.go

@@ -0,0 +1,98 @@
+// Copyright 2016 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 hex_test
+
+import (
+	"encoding/hex"
+	"fmt"
+	"log"
+	"os"
+)
+
+func ExampleEncode() {
+	src := []byte("Hello Gopher!")
+
+	dst := make([]byte, hex.EncodedLen(len(src)))
+	hex.Encode(dst, src)
+
+	fmt.Printf("%s\n", dst)
+
+	// Output:
+	// 48656c6c6f20476f7068657221
+}
+
+func ExampleDecode() {
+	src := []byte("48656c6c6f20476f7068657221")
+
+	dst := make([]byte, hex.DecodedLen(len(src)))
+	n, err := hex.Decode(dst, src)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("%s\n", dst[:n])
+
+	// Output:
+	// Hello Gopher!
+}
+
+func ExampleDecodedString() {
+	const s = "48656c6c6f20476f7068657221"
+	decoded, err := hex.DecodeString(s)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("%s\n", decoded)
+
+	// Output:
+	// Hello Gopher!
+}
+
+func ExampleDump() {
+	content := []byte("Go is an open source programming language.")
+
+	fmt.Printf("%s", hex.Dump(content))
+
+	// Output:
+	// 00000000  47 6f 20 69 73 20 61 6e  20 6f 70 65 6e 20 73 6f  |Go is an open so|
+	// 00000010  75 72 63 65 20 70 72 6f  67 72 61 6d 6d 69 6e 67  |urce programming|
+	// 00000020  20 6c 61 6e 67 75 61 67  65 2e                    | language.|
+}
+
+func ExampleDumper() {
+	lines := []string{
+		"Go is an open source programming language.",
+		"\n",
+		"We encourage all Go users to subscribe to golang-announce.",
+	}
+
+	stdoutDumper := hex.Dumper(os.Stdout)
+
+	defer stdoutDumper.Close()
+
+	for _, line := range lines {
+		stdoutDumper.Write([]byte(line))
+	}
+
+	// Output:
+	// 00000000  47 6f 20 69 73 20 61 6e  20 6f 70 65 6e 20 73 6f  |Go is an open so|
+	// 00000010  75 72 63 65 20 70 72 6f  67 72 61 6d 6d 69 6e 67  |urce programming|
+	// 00000020  20 6c 61 6e 67 75 61 67  65 2e 0a 57 65 20 65 6e  | language..We en|
+	// 00000030  63 6f 75 72 61 67 65 20  61 6c 6c 20 47 6f 20 75  |courage all Go u|
+	// 00000040  73 65 72 73 20 74 6f 20  73 75 62 73 63 72 69 62  |sers to subscrib|
+	// 00000050  65 20 74 6f 20 67 6f 6c  61 6e 67 2d 61 6e 6e 6f  |e to golang-anno|
+	// 00000060  75 6e 63 65 2e                                    |unce.|
+}
+
+func ExampleEncodeToString() {
+	src := []byte("Hello")
+	encodedStr := hex.EncodeToString(src)
+
+	fmt.Printf("%s\n", encodedStr)
+
+	// Output:
+	// 48656c6c6f
+}

src/encoding/hex/hex.go

@@ -45,10 +45,11 @@ func (e InvalidByteError) Error() string {
 
 func DecodedLen(x int) int { return x / 2 }
 
-// Decode decodes src into DecodedLen(len(src)) bytes, returning the actual
-// number of bytes written to dst.
+// Decode decodes src into DecodedLen(len(src)) bytes,
+// returning the actual number of bytes written to dst.
 //
-// If Decode encounters invalid input, it returns an error describing the failure.
+// Decode expects that src contain only hexadecimal
+// characters and that src should have an even length.
 func Decode(dst, src []byte) (int, error) {
 	if len(src)%2 == 1 {
 		return 0, ErrLength