encoding/xml: add example and docs for anon fields

Anonymous pointer fields is not yet supported.
The problem is documented in issue 3108.

R=golang-dev, rsc
CC=golang-dev
https://golang.org/cl/5694043

src/pkg/encoding/xml/example_test.go

@@ -11,6 +11,9 @@ import (
 )
 
 func ExampleMarshalIndent() {
+	type Address struct {
+		City, State string
+	}
 	type Person struct {
 		XMLName   xml.Name `xml:"person"`
 		Id        int      `xml:"id,attr"`
@@ -19,11 +22,13 @@ func ExampleMarshalIndent() {
 		Age       int      `xml:"age"`
 		Height    float32  `xml:"height,omitempty"`
 		Married   bool
-		Comment   string `xml:",comment"`
+		Address
+		Comment string `xml:",comment"`
 	}
 
 	v := &Person{Id: 13, FirstName: "John", LastName: "Doe", Age: 42}
-	v.Comment = " Need more fields. "
+	v.Comment = " Need more details. "
+	v.Address = Address{"Hanga Roa", "Easter Island"}
 
 	output, err := xml.MarshalIndent(v, "  ", "    ")
 	if err != nil {
@@ -39,7 +44,9 @@ func ExampleMarshalIndent() {
 	//       </name>
 	//       <age>42</age>
 	//       <Married>false</Married>
-	//       <!-- Need more fields. -->
+	//       <City>Hanga Roa</City>
+	//       <State>Easter Island</State>
+	//       <!-- Need more details. -->
 	//   </person>
 }
 
@@ -52,14 +59,19 @@ func ExampleUnmarshal() {
 		Where string `xml:"where,attr"`
 		Addr  string
 	}
+	type Address struct {
+		City, State string
+	}
 	type Result struct {
 		XMLName xml.Name `xml:"Person"`
 		Name    string   `xml:"FullName"`
 		Phone   string
 		Email   []Email
 		Groups  []string `xml:"Group>Value"`
+		Address
 	}
-	p := Result{Name: "none", Phone: "none"}
+	v := Result{Name: "none", Phone: "none"}
+	v.Address = Address{"Hanga Roa", "Easter Island"}
 
 	data := `
 		<Person>
@@ -77,20 +89,22 @@ func ExampleUnmarshal() {
 			<Address>123 Main Street</Address>
 		</Person>
 	`
-	err := xml.Unmarshal([]byte(data), &p)
+	err := xml.Unmarshal([]byte(data), &v)
 	if err != nil {
 		fmt.Printf("error: %v", err)
 		return
 	}
-	fmt.Printf("XMLName: %#v\n", p.XMLName)
-	fmt.Printf("Name: %q\n", p.Name)
-	fmt.Printf("Phone: %q\n", p.Phone)
-	fmt.Printf("Email: %v\n", p.Email)
-	fmt.Printf("Groups: %v\n", p.Groups)
+	fmt.Printf("XMLName: %#v\n", v.XMLName)
+	fmt.Printf("Name: %q\n", v.Name)
+	fmt.Printf("Phone: %q\n", v.Phone)
+	fmt.Printf("Email: %v\n", v.Email)
+	fmt.Printf("Groups: %v\n", v.Groups)
+	fmt.Printf("Address: %v\n", v.Address)
 	// Output:
 	// XMLName: xml.Name{Space:"", Local:"Person"}
 	// Name: "Grace R. Emlin"
 	// Phone: "none"
 	// Email: [{home gre@example.com} {work gre@work.com}]
 	// Groups: [Friends Squash]
+	// Address: {Hanga Roa Easter Island}
 }

src/pkg/encoding/xml/marshal.go

@@ -57,6 +57,8 @@ const (
 //       if the field value is empty. The empty values are false, 0, any
 //       nil pointer or interface value, and any array, slice, map, or
 //       string of length zero.
+//     - a non-pointer anonymous struct field is handled as if the
+//       fields of its value were part of the outer struct.
 //
 // If a field uses a tag "a>b>c", then the element c will be nested inside
 // parent elements a and b.  Fields that appear next to each other that name

src/pkg/encoding/xml/read.go

@@ -81,6 +81,9 @@ import (
 //      of the above rules and the struct has a field with tag ",any",
 //      unmarshal maps the sub-element to that struct field.
 //
+//   * A non-pointer anonymous struct field is handled as if the
+//      fields of its value were part of the outer struct.
+//
 //   * A struct field with tag "-" is never unmarshalled into.
 //
 // Unmarshal maps an XML element to a string or []byte by saving the