language: move package comment to doc.go
Change-Id: Idf694a566e3e3ccc1ea0a3780c55468d237db463
Reviewed-on: https://go-review.googlesource.com/59813
Run-TryBot: Marcel van Lohuizen <mpvl@golang.org>
Reviewed-by: Nigel Tao <nigeltao@golang.org>
diff --git a/language/doc.go b/language/doc.go
new file mode 100644
index 0000000..6dcbbe0
--- /dev/null
+++ b/language/doc.go
@@ -0,0 +1,100 @@
+// Copyright 2017 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package language implements BCP 47 language tags and related functionality.
+//
+// The Tag type, which is used to represent languages, is agnostic to the
+// meaning of its subtags. Tags are not fully canonicalized to preserve
+// information that may be valuable in certain contexts. As a consequence, two
+// different tags may represent identical languages.
+//
+// Initializing language- or locale-specific components usually consists of
+// two steps. The first step is to select a display language based on the
+// preferred languages of the user and the languages supported by an application.
+// The second step is to create the language-specific services based on
+// this selection. Each is discussed in more details below.
+//
+// Matching preferred against supported languages
+//
+// An application may support various languages. This list is typically limited
+// by the languages for which there exists translations of the user interface.
+// Similarly, a user may provide a list of preferred languages which is limited
+// by the languages understood by this user.
+// An application should use a Matcher to find the best supported language based
+// on the user's preferred list.
+// Matchers are aware of the intricacies of equivalence between languages.
+// The default Matcher implementation takes into account things such as
+// deprecated subtags, legacy tags, and mutual intelligibility between scripts
+// and languages.
+//
+// A Matcher for English, Australian English, Danish, and standard Mandarin can
+// be defined as follows:
+//
+// var matcher = language.NewMatcher([]language.Tag{
+// language.English, // The first language is used as fallback.
+// language.MustParse("en-AU"),
+// language.Danish,
+// language.Chinese,
+// })
+//
+// The following code selects the best match for someone speaking Spanish and
+// Norwegian:
+//
+// preferred := []language.Tag{ language.Spanish, language.Norwegian }
+// tag, _, _ := matcher.Match(preferred...)
+//
+// In this case, the best match is Danish, as Danish is sufficiently a match to
+// Norwegian to not have to fall back to the default.
+// See ParseAcceptLanguage on how to handle the Accept-Language HTTP header.
+//
+// Selecting language-specific services
+//
+// One should always use the Tag returned by the Matcher to create an instance
+// of any of the language-specific services provided by the text repository.
+// This prevents the mixing of languages, such as having a different language for
+// messages and display names, as well as improper casing or sorting order for
+// the selected language.
+// Using the returned Tag also allows user-defined settings, such as collation
+// order or numbering system to be transparently passed as options.
+//
+// If you have language-specific data in your application, however, it will in
+// most cases suffice to use the index returned by the matcher to identify
+// the user language.
+// The following loop provides an alternative in case this is not sufficient:
+//
+// supported := map[language.Tag]data{
+// language.English: enData,
+// language.MustParse("en-AU"): enAUData,
+// language.Danish: daData,
+// language.Chinese: zhData,
+// }
+// tag, _, _ := matcher.Match(preferred...)
+// for ; tag != language.Und; tag = tag.Parent() {
+// if v, ok := supported[tag]; ok {
+// return v
+// }
+// }
+// return enData // should not reach here
+//
+// Repeatedly taking the Parent of the tag returned by Match will eventually
+// match one of the tags used to initialize the Matcher.
+//
+// Canonicalization
+//
+// By default, only legacy and deprecated tags are converted into their
+// canonical equivalent. All other information is preserved. This approach makes
+// the confidence scores more accurate and allows matchers to distinguish
+// between variants that are otherwise lost.
+//
+// As a consequence, two tags that should be treated as identical according to
+// BCP 47 or CLDR, like "en-Latn" and "en", will be represented differently. The
+// Matchers will handle such distinctions, though, and are aware of the
+// equivalence relations. The CanonType type can be used to alter the
+// canonicalization form.
+//
+// References
+//
+// BCP 47 - Tags for Identifying Languages
+// http://tools.ietf.org/html/bcp47
+package language // import "golang.org/x/text/language"
diff --git a/language/language.go b/language/language.go
index f1012c9..ed1011f 100644
--- a/language/language.go
+++ b/language/language.go
@@ -5,102 +5,7 @@
//go:generate go run gen.go gen_common.go -output tables.go
//go:generate go run gen_index.go
-// Package language implements BCP 47 language tags and related functionality.
-//
-// The Tag type, which is used to represent languages, is agnostic to the
-// meaning of its subtags. Tags are not fully canonicalized to preserve
-// information that may be valuable in certain contexts. As a consequence, two
-// different tags may represent identical languages.
-//
-// Initializing language- or locale-specific components usually consists of
-// two steps. The first step is to select a display language based on the
-// preferred languages of the user and the languages supported by an application.
-// The second step is to create the language-specific services based on
-// this selection. Each is discussed in more details below.
-//
-// Matching preferred against supported languages
-//
-// An application may support various languages. This list is typically limited
-// by the languages for which there exists translations of the user interface.
-// Similarly, a user may provide a list of preferred languages which is limited
-// by the languages understood by this user.
-// An application should use a Matcher to find the best supported language based
-// on the user's preferred list.
-// Matchers are aware of the intricacies of equivalence between languages.
-// The default Matcher implementation takes into account things such as
-// deprecated subtags, legacy tags, and mutual intelligibility between scripts
-// and languages.
-//
-// A Matcher for English, Australian English, Danish, and standard Mandarin can
-// be defined as follows:
-//
-// var matcher = language.NewMatcher([]language.Tag{
-// language.English, // The first language is used as fallback.
-// language.MustParse("en-AU"),
-// language.Danish,
-// language.Chinese,
-// })
-//
-// The following code selects the best match for someone speaking Spanish and
-// Norwegian:
-//
-// preferred := []language.Tag{ language.Spanish, language.Norwegian }
-// tag, _, _ := matcher.Match(preferred...)
-//
-// In this case, the best match is Danish, as Danish is sufficiently a match to
-// Norwegian to not have to fall back to the default.
-// See ParseAcceptLanguage on how to handle the Accept-Language HTTP header.
-//
-// Selecting language-specific services
-//
-// One should always use the Tag returned by the Matcher to create an instance
-// of any of the language-specific services provided by the text repository.
-// This prevents the mixing of languages, such as having a different language for
-// messages and display names, as well as improper casing or sorting order for
-// the selected language.
-// Using the returned Tag also allows user-defined settings, such as collation
-// order or numbering system to be transparently passed as options.
-//
-// If you have language-specific data in your application, however, it will in
-// most cases suffice to use the index returned by the matcher to identify
-// the user language.
-// The following loop provides an alternative in case this is not sufficient:
-//
-// supported := map[language.Tag]data{
-// language.English: enData,
-// language.MustParse("en-AU"): enAUData,
-// language.Danish: daData,
-// language.Chinese: zhData,
-// }
-// tag, _, _ := matcher.Match(preferred...)
-// for ; tag != language.Und; tag = tag.Parent() {
-// if v, ok := supported[tag]; ok {
-// return v
-// }
-// }
-// return enData // should not reach here
-//
-// Repeatedly taking the Parent of the tag returned by Match will eventually
-// match one of the tags used to initialize the Matcher.
-//
-// Canonicalization
-//
-// By default, only legacy and deprecated tags are converted into their
-// canonical equivalent. All other information is preserved. This approach makes
-// the confidence scores more accurate and allows matchers to distinguish
-// between variants that are otherwise lost.
-//
-// As a consequence, two tags that should be treated as identical according to
-// BCP 47 or CLDR, like "en-Latn" and "en", will be represented differently. The
-// Matchers will handle such distinctions, though, and are aware of the
-// equivalence relations. The CanonType type can be used to alter the
-// canonicalization form.
-//
-// References
-//
-// BCP 47 - Tags for Identifying Languages
-// http://tools.ietf.org/html/bcp47
-package language // import "golang.org/x/text/language"
+package language
// TODO: Remove above NOTE after:
// - verifying that tables are dropped correctly (most notably matcher tables).
