intl: Improve comments.

* gettext-runtime/intl/Makefile.am: Add an overview of the code.
* gettext-runtime/intl/loadinfo.h (_nl_make_l10nflist): Improve comment.
* gettext-runtime/intl/dcigettext.c (guess_category_value): Likewise.
* gettext-runtime/intl/finddomain.c (_nl_find_domain): Likewise.

diff --git a/gettext-runtime/intl/Makefile.am b/gettext-runtime/intl/Makefile.am
index d11bc36daa4a607f162371f1e62930118a078fe6..5e5994e60bf67794898399c3349460d8ab7ab69d 100644 (file)
--- a/gettext-runtime/intl/Makefile.am
+++ b/gettext-runtime/intl/Makefile.am
@@ -106,6 +106,106 @@ EXTRA_DIST += \
   intl-exports.c os2compat.h os2compat.c \
   libgnuintl.in.h
 
+# Overview of the code
+# --------------------
+#
+# The following files implement public API, declared in libgnuintl.in.h:
+#   version.c:          libintl_version
+#   gettext.c:          libintl_gettext
+#   dgettext.c:         libintl_dgettext
+#   dcgettext.c:        libintl_dcgettext
+#   ngettext.c:         libintl_ngettext
+#   dngettext.c:        libintl_dngettext
+#   dcngettext.c:       libintl_dcngettext
+#   textdomain.c:       libintl_textdomain
+#   bindtextdom.c:      libintl_bindtextdomain
+#                       libintl_bind_textdomain_codeset
+#   printf.c:           libintl_fprintf
+#                       libintl_vfprintf
+#                       libintl_printf
+#                       libintl_vprintf
+#                       libintl_sprintf
+#                       libintl_vsprintf
+#                       libintl_snprintf
+#                       libintl_vsnprintf
+#                       libintl_asprintf
+#                       libintl_vasprintf
+#                       libintl_fwprintf
+#                       libintl_vfwprintf
+#                       libintl_wprintf
+#                       libintl_vwprintf
+#                       libintl_swprintf
+#                       libintl_vswprintf
+#   localename.c:       libintl_newlocale
+#                       libintl_duplocale
+#                       libintl_freelocale
+#   setlocale.c:        libintl_newlocale
+#                       libintl_setlocale
+#   relocatable.c:      libintl_set_relocation_prefix
+#
+# The following files implement private API.
+#   gettextP.h:     dcigettext.c:       libintl_dcigettext
+#                                       _nl_find_msg
+#                                       libintl_nl_default_dirname
+#                                       libintl_nl_domain_bindings
+#                                       libintl_nl_default_default_domain
+#                                       libintl_nl_current_default_domain
+#                   localename.c:       _nl_locale_name_canonicalize
+#                                       _nl_locale_name_from_win32_LANGID
+#                                       _nl_locale_name_from_win32_LCID
+#                                       _nl_locale_name_thread_unsafe
+#                                       _nl_locale_name_thread
+#                                       _nl_locale_name_posix
+#                                       _nl_locale_name_environ
+#                                       _nl_locale_name_default
+#                                       _nl_locale_name
+#                   langprefs.c:        _nl_language_preferences_default
+#                   finddomain.c:       _nl_find_domain
+#                   loadmsgcat.c:       _nl_load_domain
+#                                       _nl_msg_cat_cntr
+#   loadinfo.h:     l10nflist.c:        _nl_make_l10nflist
+#                                       _nl_normalize_codeset
+#                   localealias.c:      _nl_expand_alias
+#                   explodename.c:      _nl_explode_name
+#   plural-exp.h:   plural.y:           libintl_gettext_free_exp
+#                                       libintl_gettextparse
+#                   plural-exp.c:       libintl_gettext_germanic_plural
+#                                       libintl_gettext_extract_plural
+#                   eval-plural.h:      plural_eval
+#
+# Other files:
+#   gmo.h:          Describes the GNU MO file format.
+#   hash-string.h:  hash-string.c:      libintl_hash_string
+#
+# Some other files are borrowed from gnulib, some with small modifications.
+#
+# Overview of invocation hierarchy
+# --------------------------------
+#
+# The main general translation lookup function is libintl_dcigettext.
+# libintl_dcigettext
+#   \-> guess_category_value
+#         \-> _nl_locale_name_thread_unsafe
+#         \-> _nl_locale_name_posix
+#         \-> _nl_locale_name_default
+#         \-> _nl_language_preferences_default
+#   \-> _nl_find_domain
+#         \-> _nl_make_l10nflist
+#         \-> _nl_load_domain
+#         \-> _nl_expand_alias
+#         \-> _nl_explode_name
+#               \-> _nl_normalize_codeset
+#   \-> _nl_find_msg
+#         \-> _nl_load_domain
+#         \-> get_output_charset
+#   \-> plural_lookup
+#         \-> plural_eval
+#
+# _nl_load_domain loads a MO file into memory.
+# _nl_load_domain
+#   \-> _nl_find_msg (for the header entry only)
+#   \-> libintl_gettext_extract_plural
+
 LIBINTLSOURCES = \
   bindtextdom.c \
   dcgettext.c \

diff --git a/gettext-runtime/intl/dcigettext.c b/gettext-runtime/intl/dcigettext.c
index 267e4253614796f8b4c92dea2502e8a9d4ad3fbb..d0b574a251aaa66d576e9670fcbe6d0c7ae4c58d 100644 (file)
--- a/gettext-runtime/intl/dcigettext.c
+++ b/gettext-runtime/intl/dcigettext.c
@@ -1500,8 +1500,9 @@ category_to_name (int category)
 }
 #endif
 
-/* Guess value of current locale from value of the environment variables
-   or system-dependent defaults.  */
+/* Lookup or infer the value of specified category in the current locale.
+   This uses values of the environment variables LC_ALL, LC_*, LANG, LANGUAGE,
+   and/or system-dependent defaults.  */
 static const char *
 internal_function
 #ifdef IN_LIBGLOCALE

diff --git a/gettext-runtime/intl/finddomain.c b/gettext-runtime/intl/finddomain.c
index 408a47ea03dfa2e83d02975a14525989853ec191..4e28ca040fc9aa7c215c86c3286e7a792a601edb 100644 (file)
--- a/gettext-runtime/intl/finddomain.c
+++ b/gettext-runtime/intl/finddomain.c
@@ -1,5 +1,5 @@
 /* Handle list of needed message catalogs
-   Copyright (C) 1995-2019 Free Software Foundation, Inc.
+   Copyright (C) 1995-2020 Free Software Foundation, Inc.
    Written by Ulrich Drepper <drepper@gnu.org>, 1995.
 
    This program is free software: you can redistribute it and/or modify
@@ -55,8 +55,8 @@ gl_rwlock_define_initialized (static, lock);
 
 
 /* Return a data structure describing the message catalog described by
-   the DOMAINNAME and CATEGORY parameters with respect to the currently
-   established bindings.  */
+   the DIRNAME, LOCALE, and DOMAINNAME parameters with respect to the
+   currently established bindings.  */
 struct loaded_l10nfile *
 internal_function
 _nl_find_domain (const char *dirname, char *locale,

diff --git a/gettext-runtime/intl/loadinfo.h b/gettext-runtime/intl/loadinfo.h
index d4665b6457b101a39fa2293319ec271e482153f3..3d61652c4bbfbcf3a5b3a0ad4c0933c86451d173 100644 (file)
--- a/gettext-runtime/intl/loadinfo.h
+++ b/gettext-runtime/intl/loadinfo.h
@@ -1,4 +1,4 @@
-/* Copyright (C) 1996-2016, 2018 Free Software Foundation, Inc.
+/* Copyright (C) 1996-2020 Free Software Foundation, Inc.
    This file is part of the GNU C Library.
    Contributed by Ulrich Drepper <drepper@cygnus.com>, 1996.
 
@@ -84,6 +84,8 @@ extern const char *_nl_normalize_codeset (const char *codeset,
    files of the same kind, sorted in decreasing order of ->filename.
    DIRLIST and DIRLIST_LEN are an argz list of directories in which to
    look, containing at least one directory (i.e. DIRLIST_LEN > 0).
+   Outside glibc, only one directory is used, i.e.
+   DIRLIST_LEN == strlen (DIRLIST) + 1.
    MASK, LANGUAGE, TERRITORY, CODESET, NORMALIZED_CODESET, MODIFIER
    are the pieces of the locale name, as produced by _nl_explode_name().
    FILENAME is the filename suffix.