Update documentation: Move encoding/decoding docs to Marshal/Unmarshal.

decode.go

@@ -20,28 +20,9 @@ type Decoder struct {
 	lax    bool
 }
 
-// Decode parses a property list document and stores the result in the value pointed to by v.
+// Decode works like Unmarshal, except it reads the decoder stream to find property list elements.
 //
 // After Decoding, the Decoder's Format field will be set to one of the plist format constants.
-//
-// Decode uses the inverse of the encodings that Encode uses, allocating heap-borne types as necessary.
-//
-// When given a nil pointer, Decode allocates a new value for it to point to.
-//
-// To decode property list values into an interface value, Decode decodes the property list into the concrete value contained
-// in the interface value. If the interface value is nil, Decode stores one of the following in the interface value:
-//
-//     string, bool, uint64, float64
-//     []byte, for plist data
-//     []interface{}, for plist arrays
-//     map[string]interface{}, for plist dictionaries
-//
-// If a property list value is not appropriate for a given value type, Decode aborts immediately and returns an error.
-//
-// As Go does not support 128-bit types, and we don't want to pretend we're giving the user integer types (as opposed to
-// secretly passing them structs), we drop the high 64 bits of any 128-bit integers encoded in binary property lists.
-//
-// This is important because CoreFoundation serializes some large 64-bit values as 128-bit values with an empty high half.
 func (p *Decoder) Decode(v interface{}) (err error) {
 	defer func() {
 		if r := recover(); r != nil {
@@ -96,12 +77,36 @@ func (p *Decoder) Decode(v interface{}) (err error) {
 	return
 }
 
-// NewDecoder returns a Decoder that reads a property list from r.
+// NewDecoder returns a Decoder that reads property list elements from a stream reader, r.
 // NewDecoder requires a Seekable stream for the purposes of file type detection.
 func NewDecoder(r io.ReadSeeker) *Decoder {
 	return &Decoder{Format: InvalidFormat, reader: r, lax: false}
 }
 
+// Unmarshal parses a property list document and stores the result in the value pointed to by v.
+//
+// Unmarshal uses the inverse of the type encodings that Marshal uses, allocating heap-borne types as necessary.
+//
+// When given a nil pointer, Unmarshal allocates a new value for it to point to.
+//
+// To decode property list values into an interface value, Unmarshal decodes the property list into the concrete value contained
+// in the interface value. If the interface value is nil, Unmarshal stores one of the following in the interface value:
+//
+//     string, bool, uint64, float64
+//     []byte, for plist data
+//     []interface{}, for plist arrays
+//     map[string]interface{}, for plist dictionaries
+//
+// If a property list value is not appropriate for a given value type, Unmarshal aborts immediately and returns an error.
+//
+// As Go does not support 128-bit types, and we don't want to pretend we're giving the user integer types (as opposed to
+// secretly passing them structs), Unmarshal will drop the high 64 bits of any 128-bit integers encoded in binary property lists.
+// (This is important because CoreFoundation serializes some large 64-bit values as 128-bit values with an empty high half.)
+//
+// When Unmarshal encounters an OpenStep property list, it will enter a relaxed parsing mode: OpenStep property lists can only store
+// plain old data as strings, so we will attempt to recover integer, floating-point, boolean and date values wherever they are necessary.
+// (for example, if Unmarshal attempts to unmarshal an OpenStep property list into a time.Time, it will try to parse the string it
+// receives as a time.)
 func Unmarshal(data []byte, v interface{}) (err error) {
 	r := bytes.NewReader(data)
 	err = NewDecoder(r).Decode(v)

doc.go

@@ -1,5 +1,5 @@
 // Package plist implements encoding and decoding of Apple's "property list" format.
 // Property lists come in three sorts: plain text (GNUStep and OpenStep), XML and binary.
 // plist supports all of them.
-// The mapping between property list and Go objects is described in the documentation for the Encode and Decode functions.
+// The mapping between property list and Go objects is described in the documentation for the Marshal and Unmarshal functions.
 package plist

encode.go

@@ -21,37 +21,7 @@ type Encoder struct {
 	indent string
 }
 
-// Encode writes the property list encoding of v to the connection.
-//
-// Encode traverses the value v recursively.
-// Any nil values encountered, other than the root, will be silently discarded as
-// the property list format bears no representation for nil values.
-//
-// Strings, integers of varying size, floats and booleans are encoded unchanged.
-// Strings bearing non-ASCII runes will be encoded differently depending upon the property list format:
-// UTF-8 for XML property lists and UTF-16 for binary property lists.
-//
-// Slice and Array values are encoded as property list arrays, except for
-// []byte values, which are encoded as data.
-//
-// Map values encode as dictionaries. The map's key type must be string; there is no provision for encoding non-string dictionary keys.
-//
-// Struct values are encoded as dictionaries, with only exported fields being serialized. Struct field encoding may be influenced with the use of tags.
-// The tag format is:
-//
-//     `plist:"<key>[,flags...]"`
-//
-// The following flags are supported:
-//
-//     omitempty    Only include the field if it is not set to the zero value for its type.
-//
-// If the key is "-", the field is ignored.
-//
-// Anonymous struct fields are encoded as if their exported fields were exposed via the outer struct.
-//
-// Pointer values encode as the value pointed to.
-//
-// Channel, complex and function values cannot be encoded. Any attempt to do so causes Encode to return an error.
+// Encode writes the property list encoding of v to the stream.
 func (p *Encoder) Encode(v interface{}) (err error) {
 	defer func() {
 		if r := recover(); r != nil {
@@ -106,10 +76,43 @@ func NewBinaryEncoder(w io.Writer) *Encoder {
 	return NewEncoderForFormat(w, BinaryFormat)
 }
 
+// Marshal returns the property list encoding of v.
+//
+// Marshal traverses the value v recursively.
+// Any nil values encountered, other than the root, will be silently discarded as
+// the property list format bears no representation for nil values.
+//
+// Strings, integers of varying size, floats and booleans are encoded unchanged.
+// Strings bearing non-ASCII runes will be encoded differently depending upon the property list format:
+// UTF-8 for XML property lists and UTF-16 for binary property lists.
+//
+// Slice and Array values are encoded as property list arrays, except for
+// []byte values, which are encoded as data.
+//
+// Map values encode as dictionaries. The map's key type must be string; there is no provision for encoding non-string dictionary keys.
+//
+// Struct values are encoded as dictionaries, with only exported fields being serialized. Struct field encoding may be influenced with the use of tags.
+// The tag format is:
+//
+//     `plist:"<key>[,flags...]"`
+//
+// The following flags are supported:
+//
+//     omitempty    Only include the field if it is not set to the zero value for its type.
+//
+// If the key is "-", the field is ignored.
+//
+// Anonymous struct fields are encoded as if their exported fields were exposed via the outer struct.
+//
+// Pointer values encode as the value pointed to.
+//
+// Channel, complex and function values cannot be encoded. Any attempt to do so causes Marshal to return an error.
 func Marshal(v interface{}, format int) ([]byte, error) {
 	return MarshalIndent(v, format, "")
 }
 
+// MarshalIndent works like Marshal, but each property list element
+// begins on a new line and is preceded by one or more copies of indent according to its nesting depth.
 func MarshalIndent(v interface{}, format int, indent string) ([]byte, error) {
 	buf := &bytes.Buffer{}
 	enc := NewEncoderForFormat(buf, format)