locale.c: Add, move some comments, and a declaration

This adds some more comments at the beginning of a function concerning
its API, and moves them to before any declarations.

It also moves the declaration for 'done' to the block of other
declarations, and adds a PERL_UNUSED_VAR call if the code that uses it
is #ifdef'd out.  Previously it was too easy to not notice the
declaration separate from the others, and to insert code between the
two, which would not compile under C89, but only on Ultrix machines.

diff --git a/locale.c b/locale.c
index 18f5ee9..73fe055 100644 (file)
--- a/locale.c
+++ b/locale.c
@@ -416,13 +416,20 @@ Perl_my_setlocale(pTHX_ int category, const char* locale)
 int
 Perl_init_i18nl10n(pTHX_ int printwarn)
 {
-    int ok = 1;
-    /* returns
+    /* printwarn is
+     *
+     *    0 if not to output warning when setup locale is bad
+     *    1 if to output warning based on value of PERL_BADLANG
+     *    >1 if to output regardless of PERL_BADLANG
+     *
+     * returns
      *    1 = set ok or not applicable,
-     *    0 = fallback to C locale,
-     *   -1 = fallback to C locale failed
+     *    0 = fallback to a locale of lower priority
+     *   -1 = fallback to all locales failed, not even to the C locale
      */
 
+    int ok = 1;
+
 #if defined(USE_LOCALE)
     dVAR;
 
@@ -445,16 +452,18 @@ Perl_init_i18nl10n(pTHX_ int printwarn)
     char * const lc_all     = PerlEnv_getenv("LC_ALL");
     char * const lang       = PerlEnv_getenv("LANG");
     bool setlocale_failure = FALSE;
+    bool done = FALSE;
+
 
-#ifdef LOCALE_ENVIRON_REQUIRED
+#ifndef LOCALE_ENVIRON_REQUIRED
+    PERL_UNUSED_VAR(done);
+#else
 
     /*
      * Ultrix setlocale(..., "") fails if there are no environment
      * variables from which to get a locale name.
      */
 
-    bool done = FALSE;
-
 #   ifdef LC_ALL
     if (lang) {
        if (my_setlocale(LC_ALL, setlocale_init))