encoding: address further godoc concerns

encoding/ssh/filexfer/buffer.go

@@ -226,9 +226,12 @@ func (b *Buffer) AppendByteSlice(v []byte) {
 	b.b = append(b.b, v...)
 }
 
-// ConsumeString consumes a single string of UTF-8 encoded text from the Buffer.
+// ConsumeString consumes a single string of binary data from the Buffer.
 // A string is a uint32 length, followed by that number of raw bytes.
 // If Buffer does not have enough data, or defines a length larger than available, it will return ErrShortPacket.
+//
+// NOTE: Go implicitly assumes that strings contain UTF-8 encoded data.
+// All caveats on using arbitrary binary data in Go strings applies.
 func (b *Buffer) ConsumeString() (string, error) {
 	v, err := b.ConsumeByteSlice()
 	if err != nil {
@@ -238,7 +241,7 @@ func (b *Buffer) ConsumeString() (string, error) {
 	return string(v), nil
 }
 
-// AppendString appends a single string of UTF-8 encoded text into the Buffer.
+// AppendString appends a single string of binary data into the Buffer.
 // A string is a uint32 length, followed by that number of raw bytes.
 func (b *Buffer) AppendString(v string) {
 	b.AppendByteSlice([]byte(v))

encoding/ssh/filexfer/packets.go

@@ -76,6 +76,9 @@ func (p *RawPacket) MarshalBinary() ([]byte, error) {
 }
 
 // UnmarshalFrom decodes a RawPacket from the given Buffer into p.
+//
+// The Data field will take ownership of the underyling byte slice of buf.
+// The caller should not use buf after this call.
 func (p *RawPacket) UnmarshalFrom(buf *Buffer) error {
 	typ, err := buf.ConsumeUint8()
 	if err != nil {