unicode/utf8: document return value for decode errors

Also replace archaic definition of rune.

R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/5654048

diff --git a/src/pkg/unicode/utf8/utf8.go b/src/pkg/unicode/utf8/utf8.go
index a5f9983b332e7448f9c5182f6bb17e336b79af42..631533a5a3579c859d9ac9fcc3914d6df881ec3e 100644 (file)
--- a/src/pkg/unicode/utf8/utf8.go
+++ b/src/pkg/unicode/utf8/utf8.go
@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 // Package utf8 implements functions and constants to support text encoded in
-// UTF-8. This package calls a Unicode character a rune for brevity.
+// UTF-8. It includes functions to translate between runes and UTF-8 byte sequences.
 package utf8
 
 import "unicode" // only needed for a couple of constants
@@ -198,19 +198,21 @@ func FullRuneInString(s string) bool {
 }
 
 // DecodeRune unpacks the first UTF-8 encoding in p and returns the rune and its width in bytes.
+// If the encoding is invalid, it returns (RuneError, 1), an impossible result for correct UTF-8.
 func DecodeRune(p []byte) (r rune, size int) {
        r, size, _ = decodeRuneInternal(p)
        return
 }
 
 // DecodeRuneInString is like DecodeRune but its input is a string.
+// If the encoding is invalid, it returns (RuneError, 1), an impossible result for correct UTF-8.
 func DecodeRuneInString(s string) (r rune, size int) {
        r, size, _ = decodeRuneInStringInternal(s)
        return
 }
 
-// DecodeLastRune unpacks the last UTF-8 encoding in p
-// and returns the rune and its width in bytes.
+// DecodeLastRune unpacks the last UTF-8 encoding in p and returns the rune and its width in bytes.
+// If the encoding is invalid, it returns (RuneError, 1), an impossible result for correct UTF-8.
 func DecodeLastRune(p []byte) (r rune, size int) {
        end := len(p)
        if end == 0 {
@@ -244,6 +246,7 @@ func DecodeLastRune(p []byte) (r rune, size int) {
 }
 
 // DecodeLastRuneInString is like DecodeLastRune but its input is a string.
+// If the encoding is invalid, it returns (RuneError, 1), an impossible result for correct UTF-8.
 func DecodeLastRuneInString(s string) (r rune, size int) {
        end := len(s)
        if end == 0 {