rlp: tweak documentation

Author: fjl

rlp/doc.go

@@ -102,56 +102,60 @@ Signed integers, floating point numbers, maps, channels and functions cannot be
 
 Struct Tags
 
-As with encoding/json, the "-" tag ignores fields.
+As with other encoding packages, the "-" tag ignores fields.
 
     type StructWithIgnoredField struct{
         Ignored uint `rlp:"-"`
         Field   uint
     }
 
-All other supported struct tags have the purpose of modifying the mapping between
-RLP lists and Go struct fields.
-
-The "tail" tag, which may only be used on the last exported struct field, allows slurping
-up any excess list elements into a slice.
+Go struct values encode/decode as RLP lists. There are two ways of influencing the mapping
+of fields to list elements. The "tail" tag, which may only be used on the last exported
+struct field, allows slurping up any excess list elements into a slice.
 
     type StructWithTail struct{
         Field   uint
         Tail    []string `rlp:"tail"`
     }
 
 The "optional" tag says that the field may be omitted if it is zero-valued. If this tag is
-used on a struct field, all subsequent public fields must also be declared optional. When
-decoding an RLP list into a struct, optional fields may be omitted from the input list.
+used on a struct field, all subsequent public fields must also be declared optional.
+
 When encoding a struct with optional fields, the output RLP list contains all values up to
 the last non-zero optional field.
 
+When decoding into a struct, optional fields may be omitted from the end of the input
+list. For the example below, this means input lists of one, two, or three elements are
+accepted.
+
    type StructWithOptionalFields struct{
         Required  uint
         Optional1 uint `rlp:"optional"`
         Optional2 uint `rlp:"optional"`
    }
 
-The "nil" tag applies to pointer-typed fields and changes the decoding rules for the field
-such that input values of size zero decode as a nil pointer. This tag can be useful when
-decoding recursive types.
+The "nil", "nilList" and "nilString" tags apply to pointer-typed fields only, and change
+the decoding rules for the field type. For regular pointer fields without the "nil" tag,
+input values must always match the required input length exactly and the decoder does not
+produce nil values. When the "nil" tag is set, input values of size zero decode as a nil
+pointer. This is especially useful for recursive types.
 
     type StructWithNilField struct {
         Field *[3]byte `rlp:"nil"`
     }
 
-In the example above, the field allows two possible input sizes. For input 0xC180 (list
+In the example above, Field allows two possible input sizes. For input 0xC180 (a list
 containing an empty string) Field is set to nil after decoding. For input 0xC483000000 (a
 list containing a 3-byte string), Field is set to a non-nil array pointer.
 
 RLP supports two kinds of empty values: empty lists and empty strings. When using the
-"nil" tag, the kind of empty value allowed for a type is chosen automatically. A struct
-field whose Go type is a pointer to an unsigned integer, string, boolean or byte
-array/slice expects an empty RLP string. Any other pointer field type encodes/decodes as
-an empty RLP list.
+"nil" tag, the kind of empty value allowed for a type is chosen automatically. A field
+whose Go type is a pointer to an unsigned integer, string, boolean or byte array/slice
+expects an empty RLP string. Any other pointer field type encodes/decodes as an empty RLP
+list.
 
 The choice of null value can be made explicit with the "nilList" and "nilString" struct
-tags. Using these tags encodes/decodes a Go nil pointer value as the kind of empty
-RLP value defined by the tag.
+tags. Using these tags encodes/decodes a Go nil pointer value as the empty RLP value kind
+defined by the tag.
 */
 package rlp