Document things in EXTERN.h, INTERN.h

Author: khwilliamson

EXTERN.h

@@ -8,13 +8,8 @@
  *
  */
 
-/*
- * EXT:  designates a global var which is defined in perl.h
- *
- * dEXT: designates a global var which is defined in another
- *       file, so we can't count on finding it in perl.h
- *       (this practice should be avoided).
- */
+/* These are documented in INTERN.h */
+
 #undef EXT
 #undef dEXT
 #undef EXTCONST

INTERN.h

@@ -9,11 +9,32 @@
  */
 
 /*
- * EXT  designates a global var which is defined in perl.h
- * dEXT designates a global var which is defined in another
- *      file, so we can't count on finding it in perl.h
- *      (this practice should be avoided).
+
+=for apidoc  CmU||EXT
+=for apidoc_item  EXTCONST
+=for apidoc_item  dEXT
+=for apidoc_item  dEXTCONST
+
+These each designate a global variable.  The C<CONST> forms indicate that it is
+constant.
+
+The designation in F<EXTERN.h> indicates that it is defined in some other file.
+The designation in F<INTERN.h> indicates that it is defined in the including file.
+
+Use C<EXT> and C<EXTCONST> for variables which will become defined by
+#including F<perl.h>.
+
+Use C<dEXT> and C<dEXTCONST> for variables that we can't count on finding in
+F<perl.h>.  (This practice should be avoided).
+
+Examples:
+
+ EXT char PL_WARN_ALL  INIT(0);
+ EXTCONST U8 PL_revision  INIT(PERL_REVISION);
+
+=cut
  */
+
 #undef EXT
 #undef dEXT
 #undef EXTCONST
@@ -45,7 +66,28 @@
 #    endif
 #  endif
 
+/*
+=for apidoc Cm||INIT|const_expr
+
+Macro to initialize something, used like so:
+
+ EXTCONST char PL_memory_wrap[]  INIT("panic: memory wrap");
+
+It expands to nothing in F<EXTERN.h>.
+
+=cut
+*/
 #undef INIT
 #define INIT(...) = __VA_ARGS__
 
+/*
+=for apidoc C#||DOINIT
+
+When #defined, it means the code should be defining and initializing things,
+instead of declaring them to be globals external to the file.
+
+Defined in F<INTERN.h>, undefined in F<EXTERN.h>
+
+=cut
+*/
 #define DOINIT

autodoc.pl

@@ -204,6 +204,7 @@
 my $filters_scn = 'Source Filters';
 my $floating_scn = 'Floating point';
 my $genconfig_scn = 'General Configuration';
+my $global_definitions_scn = 'Declaration and Initialization of Globals';
 my $globals_scn = 'Global Variables';
 my $GV_scn = 'GV Handling and Stashes';
 my $hook_scn = 'Hook manipulation';
@@ -379,6 +380,28 @@
             =back
             EOT
       },
+    $global_definitions_scn => {
+        header => <<~'EOT',
+            Global variables are defined and initialized in one place, but
+            referred to from multiple files.  They need to be declared and any
+            initialization done in that one place, but declarations made for
+            them in each file that may refer to them.  Note that there is no
+            harm in declaring a global and not using it.
+
+            Perl has a mechanism that allows both purposes to be served while
+            minimizing code duplication.  Most files will include the file
+            F<EXTERN.h>; the few files that do the actual definitions instead
+            include the file F<INTERN.h>.  These header files #define the same
+            macros, but with different definitions.  In F<EXTERN.h>, the
+            macros expand to declarations of the globals as external to the
+            file.  In F<INTERN.h> they actually cause the space to be
+            allocated and possibly initialized.
+
+            This section documents these macros.  F<perl.h> has many uses that
+            can serve as paradigms for you.
+            EOT
+        may_be_empty_in_perlapi => 1,
+      },
     $globals_scn => {},
     $GV_scn => {},
     $hook_scn => {},
@@ -481,6 +504,7 @@
                             'gv.c' => $GV_scn,
                             'gv.h' => $GV_scn,
                             'hv.h' => $HV_scn,
+                            'INTERN.h' => $global_definitions_scn,
                             'locale.c' => $locale_scn,
                             'malloc.c' => $memory_scn,
                             'numeric.c' => $numeric_scn,