locale.c: Update comments, white-space in 2 functions

locale.c

@@ -1825,9 +1825,15 @@ S_bool_setlocale_2008_i(pTHX_
 
     /* This function effectively performs a setlocale() on just the current
      * thread; thus it is thread-safe.  It does this by using the POSIX 2008
-     * locale functions to emulate the behavior of setlocale().  By doing this,
-     * most locale-sensitive functions become thread-safe.  The exceptions are
-     * mostly those that return a pointer to static memory. */
+     * locale functions to emulate the behavior of setlocale().  Similar to
+     * regular setlocale(), the return from this function points to memory that
+     * can be overwritten by other system calls, so needs to be copied
+     * immediately if you need to retain it.  The difference here is that
+     * system calls besides another setlocale() can overwrite it.
+     *
+     * By doing this, most locale-sensitive functions become thread-safe.  The
+     * exceptions are mostly those that return a pointer to static memory.
+     */
 
     int mask = category_masks[index];
     const locale_t entry_obj = uselocale((locale_t) 0);
@@ -1867,6 +1873,7 @@ S_bool_setlocale_2008_i(pTHX_
 
     /* Without a querylocale() mechanism, we have to figure out ourselves what
      * happens with setting a locale to "" */
+
     if (strEQ(new_locale, "")) {
         new_locale = find_locale_from_environment(index);
         if (! new_locale) {
@@ -1949,14 +1956,21 @@ S_bool_setlocale_2008_i(pTHX_
                                caller_line));
         new_obj = PL_C_locale_obj;
 
-        /* And free the old object if it isn't a special one */
+        /* 'entry_obj' is now dangling, of no further use to anyone (unless it
+         * is one of the special ones).  Free it to avoid a leak */
         if (! entry_obj_is_special) {
             freelocale(entry_obj);
         }
 
         update_PL_curlocales_i(index, "C", caller_line);
     }
-    else {  /* Here is the general case, not to LC_ALL=>C */
+    else {  /* Here is the general case, not to LC_ALL => C */
+
+        /* The newlocale() call(s) below take a basis object to build upon to
+         * create the changed locale, trashing it iff successful.
+         *
+         * For the objects that are not to be modified by this function, we
+         * create a duplicate that gets trashed instead. */
         locale_t basis_obj = entry_obj;
 
         if (entry_obj_is_special) {
@@ -2021,14 +2035,16 @@ S_bool_setlocale_2008_i(pTHX_
                                       caller_line));
     }
 
-    /* Here, we are using 'new_obj' which matches the input 'new_locale'. */
     DEBUG_Lv(PerlIO_printf(Perl_debug_log,
                            "(called from %" LINE_Tf "):"
                            " bool_setlocale_2008_i: now using %p\n",
                            caller_line, new_obj));
 
-#  ifdef MULTIPLICITY
+#  ifdef MULTIPLICITY   /* Unlikely, but POSIX 2008 functions could be
+                           Configured to be used on unthreaded perls, in which
+                           case this object doesn't exist */
 
+    /* Update the current object */
     if (PL_cur_locale_obj != new_obj) {
         DEBUG_Lv(PerlIO_printf(Perl_debug_log,
                                "(called from %" LINE_Tf "):"
@@ -2042,7 +2058,8 @@ S_bool_setlocale_2008_i(pTHX_
 #  ifdef HAS_GLIBC_LC_MESSAGES_BUG
 
     /* Invalidate the glibc cache of loaded translations if the locale has
-     * changed, see [perl #134264] */
+     * changed, see [perl #134264] and
+     * https://sourceware.org/bugzilla/show_bug.cgi?id=24936 */
     if (old_messages_locale) {
         if (strNE(old_messages_locale, querylocale_c(LC_MESSAGES))) {
             textdomain(textdomain(NULL));
@@ -2099,6 +2116,9 @@ S_update_PL_curlocales_i(pTHX_
                          const char * new_locale,
                          const line_t caller_line)
 {
+    /* Update PL_curlocales[], which is parallel to the other ones indexed by
+     * our mapping of libc category number to our internal equivalents. */
+
     PERL_ARGS_ASSERT_UPDATE_PL_CURLOCALES_I;
     PERL_UNUSED_ARG(caller_line);
     assert(index <= LC_ALL_INDEX_);

perl.h

@@ -1120,7 +1120,6 @@ violations are fatal.
  * repeated in t/loc_tools.pl and makedef.pl;  The three should be kept in
  * sync. */
 #if   ! defined(NO_LOCALE)
-
 #  if ! defined(NO_POSIX_2008_LOCALE)           \
    &&   defined(HAS_NEWLOCALE)                  \
    &&   defined(HAS_USELOCALE)                  \
@@ -7297,7 +7296,6 @@ the plain locale pragma without a parameter (S<C<use locale>>) is in effect.
 #  define LOCALE_UNLOCK              NOOP
 #endif
 
-
       /* On systems that don't have per-thread locales, even though we don't
        * think we are changing the locale ourselves, behind the scenes it does
        * get changed to whatever the thread's should be, so it has to be an