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,37 @@
  */
 
 /*
- * 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.
+
+Use them like this:
+
+ Include either EXTERN.h or INTERN.h, but not both
+ ...
+ #include "perl.h"
+ ...
+ EXT char PL_WARN_ALL  INIT(0);
+ EXTCONST U8 PL_revision  INIT(PERL_REVISION);
+
+This will handle everything for you regarding whether they are to actually be
+defined and initialized or just declared C<extern>.
+
+If the initialization is complex, you may have to use C<L</DOINIT>>.
+
+If some constants you wish to reference will not become defined by #including
+F<perl.h>, instead use C<dEXT> and C<dEXTCONST> for them and include whatever
+files you need to to get them.  This is currently very rare, and should be
+avoided.
+
+=cut
  */
+
 #undef EXT
 #undef dEXT
 #undef EXTCONST
@@ -45,7 +71,38 @@
 #    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
+
+This is defined in F<INTERN.h>, undefined in F<EXTERN.h>
+
+Most of the time you can use C<L</INIT>> to initialize your data structures.
+But not always.  In such cases, you can do the following:
+
+ #ifdef DOINIT
+    ... do the declaration and definition ...
+ #else
+    declaration only
+ #endif
+
+A typical reason for needing this is when the definition includes #ifdef's.
+You can't put that portably in a call to C<INIT>, as a macro generally can't
+itself contain preprocessor directives.
+
+=cut
+*/
 #define DOINIT

autodoc.pl

@@ -198,6 +198,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';
@@ -373,6 +374,49 @@
             =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 defined and any
+            initialization done in that one place, but extern 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.  F<EXTERN.h> and F<INTERN.h> define
+            the same relatively few macros, but their definitions are
+            different.  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.
+
+            Most files will follow this paradigm:
+
+                #include "EXTERN.h"
+                ...
+                #include "perl.h">
+
+            This causes every global symbol that is referred to in F<perl.h>
+            and every file it includes (which is nearly every top level Perl
+            header file) to be declared as external.
+
+            The very few files that define globals will instead do
+
+                #include "INTERN.h"
+                ...
+                #include "perl.h">
+                include the file
+
+            It doesn't work for a file to both define some globals and refer
+            to others as externs.  That is, you can only include one of
+            F<INTERN.h> and F<EXTERN.h>.
+
+            This section documents the macros that are defined in these two
+            header files.  F<perl.h> has many uses of them that can serve as
+            paradigms for you.
+            EOT
+        may_be_empty_in_perlapi => 1,
+      },
     $globals_scn => {},
     $GV_scn => {},
     $hook_scn => {},
@@ -475,6 +519,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,