perl.h - rename PERL_DEB() to a more intuitive name

This patch renames PERL_DEB() to PERL_IF_DEBUGGING() and renames
PERL_DEB2() to PERL_IF_DEBUGGING_ELSE(). It also documents them, along
with PERL_DEBUG() and DEBUG_r() and friends.

I have switched the existing PERL_DEB() or PERL_DEB2() calls to use the
new names, but kept aliases for the old names just in case they are used
out in the wild (eg CPAN).

Thanks to mauke for the name suggestions!

Author: demerphq

perl.h

@@ -4922,8 +4922,8 @@ Gid_t getegid (void);
 #  define DEBUG_Lv_TEST DEBUG_Lv_TEST_
 #  define DEBUG_yv_TEST DEBUG_yv_TEST_
 
-#  define PERL_DEB(a)                  a
-#  define PERL_DEB2(a,b)               a
+#  define PERL_IF_DEBUGGING(a)         a
+#  define PERL_IF_DEBUGGING_ELSE(a,b)  a
 #  define PERL_DEBUG(a) if (PL_debug)  a
 #  define DEBUG_p(a) if (DEBUG_p_TEST) a
 #  define DEBUG_s(a) if (DEBUG_s_TEST) a
@@ -5051,8 +5051,8 @@ Gid_t getegid (void);
 #  define DEBUG_Lv_TEST (0)
 #  define DEBUG_yv_TEST (0)
 
-#  define PERL_DEB(a)
-#  define PERL_DEB2(a,b)               b
+#  define PERL_IF_DEBUGGING(a)
+#  define PERL_IF_DEBUGGING_ELSE(a,b)   b
 #  define PERL_DEBUG(a)
 #  define DEBUG_p(a)
 #  define DEBUG_s(a)
@@ -5088,6 +5088,90 @@ Gid_t getegid (void);
 #endif /* DEBUGGING */
 
 
+/*
+=for apidoc_section $debugging
+=for apidoc mu||PERL_IF_DEBUGGING|code
+
+A macro which is executed only when DEBUGGING is enabled. 
+Functionally identical to
+
+ #ifdef DEBUGGING
+   code
+ #endif
+
+but prettier. This macro is useful for declaring variables that are
+only used on DEBUGGING builds. Note that what this macro does is
+determined at compile time, if you want a run time equivalent then
+use C<PERL_DEBUG()> instead.
+
+=for apidoc mu||PERL_IF_DEBUGGING_ELSE|code_debugging|code_nondebugging
+
+A macro way of expressing different code that should be compiled
+depending on whether DEBUGGING is enabled. Functionally identical
+to
+
+ #ifdef DEBUGGING
+   code_debugging
+ #else
+   code_nondebugging
+ #end
+
+but prettier.
+
+=for apidoc mu||PERL_DEBUG|code
+A macro way of expressing code that will only be executed when the run
+time internal variable PL_debug is non-zero.
+
+=for apidoc mu||DEBUG_A|code
+=for apidoc_item mu||DEBUG_B|code
+=for apidoc_item mu||DEBUG_C|code
+=for apidoc_item mu||DEBUG_c|code
+=for apidoc_item mu||DEBUG_D|code
+=for apidoc_item mu||DEBUG_f|code
+=for apidoc_item mu||DEBUG_i|code
+=for apidoc_item mu||DEBUG_L|code
+=for apidoc_item mu||DEBUG_l|code
+=for apidoc_item mu||DEBUG_Lv|code
+=for apidoc_item mu||DEBUG_m|code
+=for apidoc_item mu||DEBUG_o|code
+=for apidoc_item mu||DEBUG_P|code
+=for apidoc_item mu||DEBUG_p|code
+=for apidoc_item mu||DEBUG_Pv|code
+=for apidoc_item mu||DEBUG_q|code
+=for apidoc_item mu||DEBUG_R|code
+=for apidoc_item mu||DEBUG_r|code
+=for apidoc_item mu||DEBUG_S|code
+=for apidoc_item mu||DEBUG_s|code
+=for apidoc_item mu||DEBUG_T|code
+=for apidoc_item mu||DEBUG_t|code
+=for apidoc_item mu||DEBUG_U|code
+=for apidoc_item mu||DEBUG_u|code
+=for apidoc_item mu||DEBUG_Uv|code
+=for apidoc_item mu||DEBUG_V|code
+=for apidoc_item mu||DEBUG_X|code
+=for apidoc_item mu||DEBUG_x|code
+=for apidoc_item mu||DEBUG_Xv|code
+=for apidoc_item mu||DEBUG_y|code
+=for apidoc_item mu||DEBUG_yv|code
+
+These are debugging macros similar to PERL_DEBUG() but which test
+which flags in PL_debug have been set. Each letter corresponds to
+a mode exposed by the -D option to perl. These macros only execute
+when DEBUGGING is enabled, and when the appropriate debug mode 
+has been enabled on the command line. 
+
+See L<perlrun> for details on the meaning of the different 
+switches.
+
+=cut
+*/
+
+/* these are for backwards compatibility, just in case anything out
+ * in the wild (eg CPAN) is using them. */
+#define PERL_DEB(a)     PERL_IF_DEBUGGING(a)
+#define PERL_DEB2(a,b)  PERL_IF_DEBUGGING_ELSE(a,b)
+
+
 #define DEBUG_SCOPE(where) \
     DEBUG_l( \
     Perl_deb(aTHX_ "%s scope %ld (savestack=%ld) at %s:%d\n",	\
@@ -5097,7 +5181,7 @@ Gid_t getegid (void);
 /* Keep the old croak based assert for those who want it, and as a fallback if
    the platform is so heretically non-ANSI that it can't assert.  */
 
-#define Perl_assert(what)	PERL_DEB2( 				\
+#define Perl_assert(what)       PERL_IF_DEBUGGING_ELSE(                                 \
         ((what) ? ((void) 0) :						\
             (Perl_croak_nocontext("Assertion %s failed: file \"" __FILE__ \
                         "\", line %d", STRINGIFY(what), __LINE__),	\

util.c

@@ -257,7 +257,7 @@ Perl_safesysrealloc(Malloc_t where,MEM_SIZE size)
     }
     else {
         dSAVE_ERRNO;
-        PERL_DEB(UV was_where = PTR2UV(where)); /* used in diags below */
+        PERL_IF_DEBUGGING(UV was_where = PTR2UV(where)); /* used in diags below */
 #ifdef USE_MDH
         where = (Malloc_t)((char*)where-PERL_MEMORY_DEBUG_HEADER_SIZE);
         if (size + PERL_MEMORY_DEBUG_HEADER_SIZE < size)

win32/win32.c

@@ -3493,7 +3493,7 @@ win32_tmpfd_mode(int mode)
             if (fh != INVALID_HANDLE_VALUE) {
                 int fd = win32_open_osfhandle((intptr_t)fh, mode);
                 if (fd >= 0) {
-                    PERL_DEB(dTHX;)
+                    PERL_IF_DEBUGGING(dTHX;)
                     DEBUG_p(PerlIO_printf(Perl_debug_log,
                                           "Created tmpfile=%s\n",filename));
                     return fd;
@@ -4194,7 +4194,7 @@ win32_chmod(const char *path, int mode)
 static char *
 create_command_line(char *cname, STRLEN clen, const char * const *args)
 {
-    PERL_DEB(dTHX;)
+    PERL_IF_DEBUGGING(dTHX;)
     int index;
     char *cmd, *ptr;
     const char *arg;