unicode/cldr: improve documentation

Change-Id: I376ad957a3417cc909f828786d6faf2a0d61bb1f
Reviewed-on: https://go-review.googlesource.com/101995
Run-TryBot: Marcel van Lohuizen <mpvl@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ross Light <light@google.com>

unicode/cldr/cldr.go

diff --git a/unicode/cldr/cldr.go b/unicode/cldr/cldr.go
index 2197f8a..052845f 100644
--- a/unicode/cldr/cldr.go
+++ b/unicode/cldr/cldr.go
@@ -5,14 +5,15 @@
 //go:generate go run makexml.go -output xml.go
 
 // Package cldr provides a parser for LDML and related XML formats.
-// This package is intended to be used by the table generation tools
-// for the various internationalization-related packages.
-// As the XML types are generated from the CLDR DTD, and as the CLDR standard
-// is periodically amended, this package may change considerably over time.
-// This mostly means that data may appear and disappear between versions.
-// That is, old code should keep compiling for newer versions, but data
-// may have moved or changed.
-// CLDR version 22 is the first version supported by this package.
+//
+// This package is intended to be used by the table generation tools for the
+// various packages in x/text and is not internal for historical reasons.
+//
+// As the XML types are generated from the CLDR DTD, and as the CLDR standard is
+// periodically amended, this package may change considerably over time. This
+// mostly means that data may appear and disappear between versions. That is,
+// old code should keep compiling for newer versions, but data may have moved or
+// changed. CLDR version 22 is the first version supported by this package.
 // Older versions may not work.
 package cldr // import "golang.org/x/text/unicode/cldr"
 
@@ -94,6 +95,12 @@
 
 // LDML returns the fully resolved LDML XML for loc, which must be one of
 // the strings returned by Locales.
+//
+// Deprecated: use RawLDML and implement inheritance manually or using the
+// internal cldrtree package.
+// Inheritance has changed quite a bit since the onset of this package and in
+// practice data often represented in a way where knowledge of how it was
+// inherited is relevant.
 func (cldr *CLDR) LDML(loc string) (*LDML, error) {
 	return cldr.resolve(loc)
 }

unicode/cldr/decode.go

diff --git a/unicode/cldr/decode.go b/unicode/cldr/decode.go
index 094d431..bb4d4d1 100644
--- a/unicode/cldr/decode.go
+++ b/unicode/cldr/decode.go
@@ -58,9 +58,10 @@
 			if len(d.dirFilter) > 0 && !in(d.dirFilter, m[1]) {
 				continue
 			}
-			var r io.Reader
+			var r io.ReadCloser
 			if r, err = l.Reader(i); err == nil {
 				err = d.decode(m[1], m[2], r)
+				r.Close()
 			}
 			if err != nil {
 				return nil, err

unicode/cldr/examples_test.go

diff --git a/unicode/cldr/examples_test.go b/unicode/cldr/examples_test.go
index 1a69b00..85d79d1 100644
--- a/unicode/cldr/examples_test.go
+++ b/unicode/cldr/examples_test.go
@@ -2,10 +2,85 @@
 
 import (
 	"fmt"
+	"os"
+	"path/filepath"
 
+	"golang.org/x/text/internal/gen"
 	"golang.org/x/text/unicode/cldr"
 )
 
+func ExampleDecoder() {
+	// Obtain the default CLDR reader (only for x/text packages).
+
+	var d cldr.Decoder
+
+	// Speed up decoding by setting filters for only what you need.
+	d.SetDirFilter("main", "supplemental")
+	d.SetSectionFilter("numbers", "plurals")
+
+	cldr, err := d.DecodeZip(gen.OpenCLDRCoreZip())
+	if err != nil {
+		fmt.Println("ERROR", err)
+		return
+	}
+	supplemental := cldr.Supplemental()
+
+	fmt.Println(supplemental.MeasurementData.MeasurementSystem[0].Type)
+	for _, lang := range cldr.Locales() {
+		data := cldr.RawLDML(lang)
+		fmt.Println(lang, data.Identity.Version.Number)
+	}
+}
+
+func ExampleDecoder_DecodePath() {
+	// This directory will exist if a go generate has been run in any of the
+	// packages in x/text using the cldr package.
+	path := filepath.FromSlash("../../DATA/cldr/" + cldr.Version)
+
+	var d cldr.Decoder
+
+	// Speed up decoding by setting filters for only what you need.
+	d.SetDirFilter("main")
+	d.SetSectionFilter("numbers")
+
+	cldr, err := d.DecodePath(path)
+	if err != nil {
+		// handle error
+		fmt.Println("ERROR", err)
+		return
+	}
+	for _, lang := range cldr.Locales() {
+		if numbers := cldr.RawLDML(lang).Numbers; numbers != nil {
+			fmt.Println(lang, len(numbers.Symbols))
+		}
+	}
+}
+
+func ExampleDecoder_DecodeZip() {
+	// This directory will exist if a go generate has been run in any of the
+	// packages in x/text using the cldr package.
+	path := filepath.FromSlash("../../DATA/cldr/" + cldr.Version)
+
+	var d cldr.Decoder
+
+	r, err := os.Open(filepath.Join(path, "core.zip"))
+	if err != nil {
+		fmt.Println("error:", err)
+		return
+	}
+
+	// Only loading supplemental data can be done much faster using a dir
+	// filter.
+	d.SetDirFilter("supplemental")
+	cldr, err := d.DecodeZip(r)
+	if err != nil {
+		fmt.Println("error:", err)
+		return
+	}
+
+	fmt.Println(cldr.Supplemental().MeasurementData.MeasurementSystem[0].Type)
+}
+
 func ExampleSlice() {
 	var dr *cldr.CLDR // assume this is initialized