perlapi: Remove per-thread section; move to real scns

Instead of having a grab bag section of all interpreter variables, move
their documentation to the section that they actually fit under.

2 files changed, 67 insertions, 7 deletions

diff --git a/autodoc.pl b/autodoc.pl
index 64491e7517..9df6266a9e 100644
--- a/autodoc.pl
+++ b/autodoc.pl
@@ -139,7 +139,6 @@ my $pack_scn = 'Pack and Unpack';
 my $pad_scn = 'Pad Data Structures';
 my $password_scn = 'Password and Group access';
 my $paths_scn = 'Paths to system commands';
-my $intrpvar_scn = 'Per-Interpreter Variables';
 my $prototypes_scn = 'Prototype information';
 my $regexp_scn = 'REGEXP Functions';
 my $signals_scn = 'Signals';
@@ -301,7 +300,6 @@ my %valid_sections = (
     $pad_scn => {},
     $password_scn => {},
     $paths_scn => {},
-    $intrpvar_scn => {},
     $prototypes_scn => {},
     $regexp_scn => {},
     $signals_scn => {},
diff --git a/intrpvar.h b/intrpvar.h
index 10fd8e13a6..67ff94ce2f 100644
--- a/intrpvar.h
+++ b/intrpvar.h
@@ -10,10 +10,6 @@
 
 #include "handy.h"
 
-/*
-=for apidoc_section Per-Interpreter Variables
-*/
-
 /* These variables are per-interpreter in threaded/multiplicity builds,
  * global otherwise.
 
@@ -123,6 +119,10 @@ PERLVARI(I, utf8cache, I8, PERL___I)	/* Is the utf8 caching code enabled? */
 
 The GV representing C<*_>.  Useful for access to C<$_>.
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =cut
 */
 
@@ -135,6 +135,10 @@ PERLVAR(I, defgv,	GV *)           /* the *_ glob */
 
 The stash for the package code will be compiled into.
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =cut
 */
 
@@ -148,6 +152,10 @@ PERLVAR(I, curstash,	HV *)		/* symbol table for current package */
 The currently active COP (control op) roughly representing the current
 statement in the source.
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =cut
 */
 
@@ -176,7 +184,7 @@ PERLVAR(I, regmatch_state, regmatch_state *)
 PERLVAR(I, comppad,	PAD *)		/* storage for lexically scoped temporaries */
 
 /*
-=for apidoc_section Per-Interpreter Variables
+=for apidoc_section $SV
 =for apidoc Amn|SV|PL_sv_undef
 This is the C<undef> SV.  Always refer to this as C<&PL_sv_undef>.
 
@@ -248,18 +256,31 @@ PERLVAR(I, statgv,	GV *)
 PERLVARI(I, statname,	SV *,	NULL)
 
 /*
+=for apidoc_section $io
 =for apidoc mn|SV*|PL_rs
 
 The input record separator - C<$/> in Perl space.
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =for apidoc mn|GV*|PL_last_in_gv
 
 The GV which was last used for a filehandle input operation.  (C<< <FH> >>)
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =for apidoc mn|GV*|PL_ofsgv
 
 The glob containing the output field separator - C<*,> in Perl space.
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =cut
 */
 
@@ -299,6 +320,7 @@ PERLVARI(I, dumpindent,	U16,	4)	/* number of blanks per dump
 					   indentation level */
 
 /*
+=for apidoc_section $embedding
 =for apidoc Amn|U8|PL_exit_flags
 
 Contains flags controlling perl's behaviour on exit():
@@ -331,6 +353,10 @@ Set by the L<perlfunc/exit> operator.
 =for apidoc Amnh||PERL_EXIT_DESTRUCT_END
 =for apidoc Amnh||PERL_EXIT_WARN
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =cut
 */
 
@@ -352,6 +378,7 @@ PERLVARA(I, locale_utf8ness, 256, char)
 PERLVARA(I, colors,6,	char *)		/* values from PERL_RE_COLORS env var */
 
 /*
+=for apidoc_section $optree_construction
 =for apidoc Amn|peep_t|PL_peepp
 
 Pointer to the per-subroutine peephole optimiser.  This is a function
@@ -369,6 +396,10 @@ If the new code wishes to operate on ops throughout the subroutine's
 structure, rather than just at the top level, it is likely to be more
 convenient to wrap the L</PL_rpeepp> hook.
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =cut
 */
 
@@ -393,6 +424,10 @@ If the new code wishes to operate only on ops at a subroutine's top level,
 rather than throughout the structure, it is likely to be more convenient
 to wrap the L</PL_peepp> hook.
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =cut
 */
 
@@ -407,6 +442,10 @@ It is also assured to first fire for the parent OP and then for its kids.
 
 When you replace this variable, it is considered a good practice to store the possibly previously installed hook and that you recall it inside your own.
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =cut
 */
 
@@ -481,12 +520,17 @@ PERLVAR(I, DBgv,	GV *)		/*  *DB::DB     */
 PERLVAR(I, DBline,	GV *)		/*  *DB::line   */
 
 /*
+=for apidoc_section $debugging
 =for apidoc mn|GV *|PL_DBsub
 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
 the SV which holds the name of the sub being debugged.  This is the C
 variable which corresponds to Perl's $DB::sub variable.  See
 C<L</PL_DBsingle>>.
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =for apidoc mn|SV *|PL_DBsingle
 When Perl is run in debugging mode, with the B<-d> switch, this SV is a
 boolean which indicates whether subs are being single-stepped.
@@ -494,11 +538,19 @@ Single-stepping is automatically turned on after every step.  This is the C
 variable which corresponds to Perl's $DB::single variable.  See
 C<L</PL_DBsub>>.
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =for apidoc mn|SV *|PL_DBtrace
 Trace variable used when Perl is run in debugging mode, with the B<-d>
 switch.  This is the C variable which corresponds to Perl's $DB::trace
 variable.  See C<L</PL_DBsingle>>.
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =cut
 */
 
@@ -567,6 +619,7 @@ PERLVARI(I, exitlist,	PerlExitListEntry *, NULL)
 					/* list of exit functions */
 
 /*
+=for apidoc_section $HV
 =for apidoc Amn|HV*|PL_modglobal
 
 C<PL_modglobal> is a general purpose, interpreter global HV for use by
@@ -575,6 +628,10 @@ In a pinch, it can also be used as a symbol table for extensions
 to share data among each other.  It is a good idea to use keys
 prefixed by the package name of the extension that owns the data.
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =cut
 */
 
@@ -701,6 +758,7 @@ PERLVAR(I, unsafe,	bool)
 PERLVAR(I, colorset,	bool)		/* PERL_RE_COLORS env var is in use */
 
 /*
+=for apidoc_section $embedding
 =for apidoc Amn|signed char|PL_perl_destruct_level
 
 This value may be set when embedding for full cleanup.
@@ -720,6 +778,10 @@ Possible values:
 If C<$ENV{PERL_DESTRUCT_LEVEL}> is set to an integer greater than the
 value of C<PL_perl_destruct_level> its value is used instead.
 
+On threaded perls, each thread has an independent copy of this variable;
+each initialized at creation time with the current value of the creating
+thread's copy.
+
 =cut
 */
 /* mod_perl is special, and also assigns a meaning -1 */