Rework enumdata.py's comments

Turn the large comment at the start into a doc-string and add some
more details to it. Fix the Ivory Coast comment's indent and a typo in
it.

Change-Id: I36b4e5094d3c3d5c5b91809424b424bcac5daafa
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

util/locale_database/enumdata.py

@@ -1,34 +1,60 @@
 # Copyright (C) 2021 The Qt Company Ltd.
 # SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
 
-# A run of cldr2qlocalexml.py will produce output reporting any
+"""Assorted enumerations implicated in public API.
-# language, script and territory codes it sees, in data, for which it
-# can find a name (taken always from en.xml) that could potentially be
-# used. There is no point adding a mapping for such a code unless the
-# CLDR's common/main/ contains an XML file for at least one locale
-# that exercises it (and little point absent substantial data).
 
-# Each *_map reflects the current values of its enums in qlocale.h; if
+The numberings of these enumerations can only change at major
-# new xml language files are available in CLDR, these languages and
+versions. When new CLDR data implies adding entries, the new ones must
-# territories need to be *appended* to this list (for compatibility
+go after all existing ones. See also zonedata.py for enumerations
-# between versions). Include any spaces and dashes present in names
+related to timezones and CLDR, which can more freely be changed
-# (they'll be squished them out for the enum entries) in *_map, but
+between versions.
-# use the squished forms of names in the *_aliases mappings. The
-# squishing also turns the first letter of each word into a capital so
-# you can safely preserve the case of en.xml's name; but omit (or
-# replace with space) any punctuation aside from dashes and map any
-# accented letters to their un-accented plain ASCII.
 
-# For a new major version (and only then), we can change the
+A run of cldr2qlocalexml.py will produce output reporting any
-# numbering, so re-sort each list into alphabetic order (e.g. using
+language, script and territory codes it sees, in data, for which it
-# sort -k2); but keep the Any and C entries first. That's why those
+can find a name (taken always from en.xml) that could potentially be
-# are offset with a blank line, below. After doing that, regenerate
+used. There is no point adding a mapping for such a code unless the
-# locale data as usual; this will cause a binary-incompatible change.
+CLDR's common/main/ contains an XML file for at least one locale that
+exercises it (and little point, even then, absent substantial data,
+ignoring draft='unconfirmed' entries).
 
-# Note on "macrolanguage" comments: see QTBUG-107781 and "ISO 639
+Each *_map reflects the current values of its enums in qlocale.h; if
-# macrolanguage" on Wikipedia. A "macrolanguage" is (loosely-speaking)
+new xml language files are available in CLDR, these languages and
-# a group of languages so closely related to one another that they
+territories need to be *appended* to this list (for compatibility
-# could also be regarded as divergent dialects of the macrolanguage.
+between versions). Include any spaces and dashes present in names
+(they'll be squished out for the enum entries) in *_map, but use the
+squished forms of names in the *_aliases mappings. The squishing also
+turns the first letter of each word into a capital so you can safely
+preserve the case of en.xml's name; but omit (or replace with space)
+any punctuation aside from dashes and map any accented letters to
+their un-accented plain ASCII. The two tables, for each enum, have
+the forms:
+* map { Numeric value: ("Proper name", "ISO code") }
+* alias { "OldName": "CurrentName" }
+
+TODO: add support for marking entries as deprecated from a specified
+version. For aliases that merely deprecates the name. Where we have a
+name for which CLDR offers no data, we may also want to deprecate
+entries in the map - although they may be worth keeping for the
+benefit of QLocaleSelector (see QTBUG-112765), if other
+locale-specific resources might have use of them.
+
+For a new major version (and only then), we can change the numbering,
+so re-sort each list into alphabetic order (e.g. using sort -k2); but
+keep the Any and C entries first. That's why those are offset with a
+blank line, below. After doing that, regenerate locale data as usual;
+this will cause a binary-incompatible change.
+
+Note on 'macrolanguage' comments: see QTBUG-107781 and 'ISO 639
+macrolanguage' on Wikipedia. A 'macrolanguage' is (loosely-speaking) a
+group of languages so closely related to one another that they could
+also be regarded as divergent dialects of the macrolanguage.  In some
+cases this may mean a resource (such as translation or text-to-speech
+data) may describe itself as pertaining to the macrolanguage, implying
+its suitability for use in any of the languages within the
+macrolanguage. For example, no_NO might be used for a generic
+Norwegian resource, embracing both nb_NO and nn_NO.
+
+"""
 
 language_map = {
       0: ("AnyLanguage",                 "  "),
@@ -530,9 +556,9 @@ territory_map = {
     115: ("Isle of Man",                                  "IM"),
     116: ("Israel",                                       "IL"),
     117: ("Italy",                                        "IT"),
-      # Officially Côte d’Ivoire, which we'd ned to map to CotedIvoire
+    # Officially Côte d’Ivoire, which we'd need to map to CotedIvoire
-      # or CoteDIvoire, either failing to make the d' separate from
+    # or CoteDIvoire, either failing to make the d' separate from Cote
-      # Cote or messing with its case. So stick with Ivory Coast:
+    # or messing with its case. So stick with Ivory Coast:
     118: ("Ivory Coast",                                  "CI"),
     119: ("Jamaica",                                      "JM"),
     120: ("Japan",                                        "JP"),