Missed the =head1 additions.

p4raw-id: //depot/perl@14041

26 files changed, 119 insertions, 5 deletions

diff --git a/XSUB.h b/XSUB.h
index a6dfdc4c6c..5066ee2113 100644
--- a/XSUB.h
+++ b/XSUB.h
@@ -4,6 +4,8 @@
 /* first, some documentation for xsubpp-generated items */
 
 /*
+=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
+
 =for apidoc Amn|char*|CLASS
 Variable which is setup by C<xsubpp> to indicate the 
 class name for a C++ XS constructor.  This is always a C<char*>.  See C<THIS>.
@@ -98,6 +100,8 @@ handled automatically by C<xsubpp>.
 /* Typically used to return values from XS functions.       */
 
 /*
+=head1 Stack Manipulation Macros
+
 =for apidoc Am|void|XST_mIV|int pos|IV iv
 Place an integer into the specified position C<pos> on the stack.  The
 value is stored in a new mortal SV.
@@ -147,6 +151,8 @@ Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
 =for apidoc Ams||XSRETURN_EMPTY
 Return an empty list from an XSUB immediately.
 
+=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
+
 =for apidoc AmU||newXSproto
 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
 the subs.
diff --git a/av.c b/av.c
index 8a4f855645..fdcdb823e1 100644
--- a/av.c
+++ b/av.c
@@ -12,6 +12,10 @@
  * meant that things should remain where they had set them)." --Treebeard
  */
 
+/*
+=head1 Array Manipulation Functions
+*/
+
 #include "EXTERN.h"
 #define PERL_IN_AV_C
 #include "perl.h"
diff --git a/av.h b/av.h
index def66b98d0..0d041b67e9 100644
--- a/av.h
+++ b/av.h
@@ -46,9 +46,13 @@ struct xpvav {
 #define AVf_REUSED 4	/* got undeffed--don't turn old memory into SVs now */
 
 /*
+=head1 Handy Values
+
 =for apidoc AmU||Nullav
 Null AV pointer.
 
+=head1 Array Manipulation Functions
+
 =for apidoc Am|int|AvFILL|AV* av
 Same as C<av_len()>.  Deprecated, use C<av_len()> instead.
 
diff --git a/cop.h b/cop.h
index 9f17b2c763..0040cbeac9 100644
--- a/cop.h
+++ b/cop.h
@@ -388,7 +388,9 @@ struct context {
 
 #define CXINC (cxstack_ix < cxstack_max ? ++cxstack_ix : (cxstack_ix = cxinc()))
 
-/* "gimme" values */
+/* 
+=head1 "Gimme" Values
+*/
 
 /*
 =for apidoc AmU||G_SCALAR
diff --git a/cv.h b/cv.h
index 8e7cad681f..8591f6bb74 100644
--- a/cv.h
+++ b/cv.h
@@ -37,9 +37,13 @@ struct xpvcv {
 };
 
 /*
+=head1 Handy Values
+
 =for apidoc AmU||Nullcv
 Null CV pointer.
 
+=head1 CV Manipulation Functions
+
 =for apidoc Am|HV*|CvSTASH|CV* cv
 Returns the stash of the CV.
 
diff --git a/doio.c b/doio.c
index 32427eb232..be27b93b07 100644
--- a/doio.c
+++ b/doio.c
@@ -2106,6 +2106,8 @@ Perl_do_shmio(pTHX_ I32 optype, SV **mark, SV **sp)
 #endif /* SYSV IPC */
 
 /*
+=head1 IO Functions
+
 =for apidoc start_glob
 
 Function called by C<do_readline> to spawn a glob (or do the glob inside
diff --git a/gv.c b/gv.c
index eb7b3ba270..d5f19746c6 100644
--- a/gv.c
+++ b/gv.c
@@ -16,6 +16,10 @@
  * laughed Pippin.
  */
 
+/*
+=head1 GV Functions
+*/
+
 #include "EXTERN.h"
 #define PERL_IN_GV_C
 #include "perl.h"
diff --git a/gv.h b/gv.h
index 428ab770b1..6dd206c491 100644
--- a/gv.h
+++ b/gv.h
@@ -35,6 +35,8 @@ struct gp {
 #define GvFLAGS(gv)	(GvXPVGV(gv)->xgv_flags)
 
 /*
+=head1 GV Functions
+
 =for apidoc Am|SV*|GvSV|GV* gv
 
 Return the SV from the GV.
diff --git a/handy.h b/handy.h
index c792665df9..1acfb0d6a4 100644
--- a/handy.h
+++ b/handy.h
@@ -21,9 +21,10 @@
 #define Null(type) ((type)NULL)
 
 /*
-=for apidoc AmU||Nullch
-Null character pointer.
+=head1 Handy Values
 
+=for apidoc AmU||Nullch 
+Null character pointer.
 =for apidoc AmU||Nullsv
 Null SV pointer.
 
@@ -210,6 +211,8 @@ typedef U64TYPE U64;
 #define Ctl(ch) ((ch) & 037)
 
 /*
+=head1 Miscellaneous Functions
+
 =for apidoc Am|bool|strNE|char* s1|char* s2
 Test two strings to see if they are different.  Returns true or
 false.
@@ -283,6 +286,9 @@ C<strncmp>).
 #endif
 
 /*
+
+=head1 Character classes
+
 =for apidoc Am|bool|isALNUM|char ch
 Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
 character (including underscore) or digit.
@@ -515,6 +521,8 @@ typedef U16 line_t;
 */
 
 /*
+=head1 SV Manipulation Functions
+
 =for apidoc Am|SV*|NEWSV|int id|STRLEN len
 Creates a new SV.  A non-zero C<len> parameter indicates the number of
 bytes of preallocated string space the SV should have.  An extra byte for a
@@ -522,6 +530,8 @@ tailing NUL is also reserved.  (SvPOK is not set for the SV even if string
 space is allocated.)  The reference count for the new SV is set to 1.
 C<id> is an integer id between 0 and 1299 (used to identify leaks).
 
+=head1 Memory Management
+
 =for apidoc Am|void|New|int id|void* ptr|int nitems|type
 The XSUB-writer's interface to the C C<malloc> function.
 
diff --git a/hv.h b/hv.h
index 3a3d867919..260125949a 100644
--- a/hv.h
+++ b/hv.h
@@ -63,14 +63,20 @@ struct xpvhv {
     } STMT_END
 
 /*
+=head1 Hash Manipulation Functions
+
 =for apidoc AmU||HEf_SVKEY
 This flag, used in the length slot of hash entries and magic structures,
 specifies the structure contains an C<SV*> pointer where a C<char*> pointer
 is to be expected. (For information only--not to be used).
 
+=head1 Handy Values
+
 =for apidoc AmU||Nullhv
 Null HV pointer.
 
+=head1 Hash Manipulation Functions
+
 =for apidoc Am|char*|HvNAME|HV* stash
 Returns the package name of a stash.  See C<SvSTASH>, C<CvSTASH>.
 
diff --git a/intrpvar.h b/intrpvar.h
index c46c8c1a30..3d08143fb6 100644
--- a/intrpvar.h
+++ b/intrpvar.h
@@ -38,6 +38,8 @@ PERLVAR(Iminus_F,	bool)
 PERLVAR(Idoswitches,	bool)
 
 /*
+=head1 Global Variables
+
 =for apidoc mn|bool|PL_dowarn
 
 The C variable which corresponds to Perl's $^W warning variable.
diff --git a/mg.c b/mg.c
index 4369e4ae10..c089c8bc21 100644
--- a/mg.c
+++ b/mg.c
@@ -12,6 +12,10 @@
  * come here, and I don't want to see no more magic,' he said, and fell silent."
  */
 
+/*
+=head1 Magical Functions
+*/
+
 #include "EXTERN.h"
 #define PERL_IN_MG_C
 #include "perl.h"
diff --git a/numeric.c b/numeric.c
index ba2f5b84c6..0c88db1985 100644
--- a/numeric.c
+++ b/numeric.c
@@ -12,6 +12,10 @@
  * wizards count differently to other people."
  */
 
+/*
+=head1 Numeric functions
+*/
+
 #include "EXTERN.h"
 #define PERL_IN_NUMERIC_C
 #include "perl.h"
diff --git a/op.c b/op.c
index 047fe6ddf0..2cd4d7f671 100644
--- a/op.c
+++ b/op.c
@@ -15,6 +15,7 @@
  * either way, as the saying is, if you follow me."  --the Gaffer
  */
 
+
 #include "EXTERN.h"
 #define PERL_IN_OP_C
 #include "perl.h"
@@ -3453,6 +3454,8 @@ Perl_utilize(pTHX_ int aver, I32 floor, OP *version, OP *id, OP *arg)
 }
 
 /*
+=head1 Embedding Functions
+
 =for apidoc load_module
 
 Loads the module whose name is pointed to by the string part of name.
@@ -4632,6 +4635,9 @@ Perl_cv_ckproto(pTHX_ CV *cv, GV *gv, char *p)
 static void const_sv_xsub(pTHX_ CV* cv);
 
 /*
+
+=head1 Optree Manipulation Functions
+
 =for apidoc cv_const_sv
 
 If C<cv> is a constant sub eligible for inlining. returns the constant
diff --git a/op.h b/op.h
index 33484358f6..2bfdced273 100644
--- a/op.h
+++ b/op.h
@@ -59,6 +59,8 @@ typedef U64TYPE PADOFFSET;
 	 dfl)
 
 /*
+=head1 "Gimme" Values
+
 =for apidoc Amn|U32|GIMME_V
 The XSUB-writer's equivalent to Perl's C<wantarray>.  Returns C<G_VOID>,
 C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
diff --git a/perl.c b/perl.c
index a96fbbd093..e7f7ad6c85 100644
--- a/perl.c
+++ b/perl.c
@@ -102,6 +102,8 @@ perl_alloc_using(struct IPerlMem* ipM, struct IPerlMem* ipMS,
 #else
 
 /*
+=head1 Embedding Functions
+
 =for apidoc perl_alloc
 
 Allocates a new Perl interpreter.  See L<perlembed>.
@@ -1622,6 +1624,8 @@ S_run_body(pTHX_ I32 oldscope)
 }
 
 /*
+=head1 SV Manipulation Functions
+
 =for apidoc p||get_sv
 
 Returns the SV of the specified Perl scalar.  If C<create> is set and the
@@ -1649,6 +1653,8 @@ Perl_get_sv(pTHX_ const char *name, I32 create)
 }
 
 /*
+=head1 Array Manipulation Functions
+
 =for apidoc p||get_av
 
 Returns the AV of the specified Perl array.  If C<create> is set and the
@@ -1670,6 +1676,8 @@ Perl_get_av(pTHX_ const char *name, I32 create)
 }
 
 /*
+=head1 Hash Manipulation Functions
+
 =for apidoc p||get_hv
 
 Returns the HV of the specified Perl hash.  If C<create> is set and the
@@ -1691,6 +1699,8 @@ Perl_get_hv(pTHX_ const char *name, I32 create)
 }
 
 /*
+=head1 CV Manipulation Functions
+
 =for apidoc p||get_cv
 
 Returns the CV of the specified Perl subroutine.  If C<create> is set and
@@ -1722,6 +1732,9 @@ Perl_get_cv(pTHX_ const char *name, I32 create)
 /* Be sure to refetch the stack pointer after calling these routines. */
 
 /*
+
+=head1 Callback Functions
+
 =for apidoc p||call_argv
 
 Performs a callback to the specified Perl sub.  See L<perlcall>.
@@ -2103,6 +2116,8 @@ Perl_eval_pv(pTHX_ const char *p, I32 croak_on_error)
 /* Require a module. */
 
 /*
+=head1 Embedding Functions
+
 =for apidoc p||require_pv
 
 Tells Perl to C<require> the file named by the string argument.  It is
diff --git a/pp.h b/pp.h
index 1d9a9339cc..ac64fe2c7c 100644
--- a/pp.h
+++ b/pp.h
@@ -18,6 +18,8 @@
 #define PP(s) OP * Perl_##s(pTHX)
 
 /*
+=head1 Stack Manipulation Macros
+
 =for apidoc AmU||SP
 Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
 C<SPAGAIN>.
diff --git a/pp_sort.c b/pp_sort.c
index e758984167..582bd4e7c0 100644
--- a/pp_sort.c
+++ b/pp_sort.c
@@ -1368,6 +1368,8 @@ S_qsortsv(pTHX_ gptr *list1, size_t nmemb, SVCOMPARE_t cmp)
 }
 
 /*
+=head1 Array Manipulation Functions
+
 =for apidoc sortsv
 
 Sort an array. Here is an example:
diff --git a/scope.h b/scope.h
index edf7ffef48..f0abb724b3 100644
--- a/scope.h
+++ b/scope.h
@@ -55,6 +55,8 @@
 #define SSPOPDXPTR (PL_savestack[--PL_savestack_ix].any_dxptr)
 
 /*
+=head1 Callback Functions
+
 =for apidoc Ams||SAVETMPS
 Opening bracket for temporaries on a callback.  See C<FREETMPS> and
 L<perlcall>.
diff --git a/sharedsv.c b/sharedsv.c
index e4b6e0ff36..f0cba10d98 100644
--- a/sharedsv.c
+++ b/sharedsv.c
@@ -33,6 +33,8 @@
  */
 
 /*
+=head1 Shared SV Functions
+
 =for apidoc sharedsv_init
 
 Saves a space for keeping SVs wider than an interpreter,
diff --git a/sv.c b/sv.c
index ba51738c28..ce4b8bf124 100644
--- a/sv.c
+++ b/sv.c
@@ -216,6 +216,8 @@ S_del_sv(pTHX_ SV *p)
 
 
 /*
+=head1 SV Manipulation Functions
+
 =for apidoc sv_add_arena
 
 Given a chunk of memory, link it to the head of the list of arenas,
@@ -10386,6 +10388,8 @@ perl_clone_using(PerlInterpreter *proto_perl, UV flags,
 #endif /* USE_ITHREADS */
 
 /*
+=head1 Unicode Support
+
 =for apidoc sv_recode_to_utf8
 
 The encoding is assumed to be an Encode object, on entry the PV
diff --git a/sv.h b/sv.h
index a80989a7fa..7c07988518 100644
--- a/sv.h
+++ b/sv.h
@@ -12,6 +12,8 @@
 #endif
 
 /*
+=head1 SV Flags
+
 =for apidoc AmU||svtype
 An enum of flags for Perl types.  These are found in the file B<sv.h>
 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
@@ -98,6 +100,8 @@ struct io {
 };
 
 /*
+=head1 SV Manipulation Functions
+
 =for apidoc Am|U32|SvREFCNT|SV* sv
 Returns the value of the object's reference count.
 
@@ -1139,6 +1143,8 @@ incremented.
 /* the following macros update any magic values this sv is associated with */
 
 /*
+=head1 Magical Functions
+
 =for apidoc Am|void|SvGETMAGIC|SV* sv
 Invokes C<mg_get> on an SV if it has 'get' magic.  This macro evaluates its
 argument more than once.
@@ -1161,6 +1167,8 @@ Like C<SvSetSV>, but does any set magic required afterwards.
 =for apidoc Am|void|SvSetMagicSV_nosteal|SV* dsv|SV* ssv
 Like C<SvSetMagicSV>, but does any set magic required afterwards.
 
+=head1 SV Manipulation Functions
+
 =for apidoc Am|char *|SvGROW|SV* sv|STRLEN len
 Expands the character buffer in the SV so that it has room for the
 indicated number of bytes (remember to reserve space for an extra trailing
diff --git a/thrdvar.h b/thrdvar.h
index e517c1e908..b23dafcf8c 100644
--- a/thrdvar.h
+++ b/thrdvar.h
@@ -1,3 +1,7 @@
+/*
+=head1 Global Variables
+*/
+
 /***********************************************/
 /* Global only to current thread               */
 /***********************************************/
diff --git a/universal.c b/universal.c
index 868fe55140..8fc7d699a8 100644
--- a/universal.c
+++ b/universal.c
@@ -93,6 +93,8 @@ S_isa_lookup(pTHX_ HV *stash, const char *name, int len, int level)
 }
 
 /*
+=head1 SV Manipulation Functions
+
 =for apidoc sv_derived_from
 
 Returns a boolean indicating whether the SV is derived from the specified
diff --git a/utf8.c b/utf8.c
index 2b5ae4202b..93c112837b 100644
--- a/utf8.c
+++ b/utf8.c
@@ -24,9 +24,9 @@
 #define PERL_IN_UTF8_C
 #include "perl.h"
 
-/* Unicode support */
+/* 
+=head1 Unicode Support
 
-/*
 =for apidoc A|U8 *|uvuni_to_utf8_flags|U8 *d|UV uv|UV flags
 
 Adds the UTF8 representation of the Unicode codepoint C<uv> to the end
diff --git a/util.c b/util.c
index 1d2048b7ba..a8e7553ae2 100644
--- a/util.c
+++ b/util.c
@@ -488,6 +488,8 @@ Perl_rninstr(pTHX_ register const char *big, const char *bigend, const char *lit
    If FBMcf_TAIL, the table is created as if the string has a trailing \n. */
 
 /*
+=head1 Miscellaneous Functions
+
 =for apidoc fbm_compile
 
 Analyses the string in order to make fast searches on it using fbm_instr()
@@ -877,6 +879,8 @@ Perl_ibcmp_locale(pTHX_ const char *s1, const char *s2, register I32 len)
 /* copy a string to a safe spot */
 
 /*
+=head1 Memory Management
+
 =for apidoc savepv
 
 Copy a string to a safe spot.  This does not use an SV.
@@ -955,6 +959,7 @@ Perl_form_nocontext(const char* pat, ...)
 #endif /* PERL_IMPLICIT_CONTEXT */
 
 /*
+=head1 Miscellaneous Functions
 =for apidoc form
 
 Takes a sprintf-style format pattern and conventional
@@ -1285,6 +1290,8 @@ Perl_croak_nocontext(const char *pat, ...)
 #endif /* PERL_IMPLICIT_CONTEXT */
 
 /*
+=head1 Warning and Dieing
+
 =for apidoc croak
 
 This is the XSUB-writer's interface to Perl's C<die> function.
@@ -3759,6 +3766,8 @@ return FALSE
         (dp->d_name[1] == '.' && dp->d_name[2] == '\0')))
 
 /*
+=head1 Miscellaneous Functions
+
 =for apidoc getcwd_sv
 
 Fill the sv with current working directory
@@ -3921,6 +3930,8 @@ Perl_getcwd_sv(pTHX_ register SV *sv)
 }
 
 /*
+=head1 SV Manipulation Functions
+
 =for apidoc new_vstring
 
 Returns a pointer to the next character after the parsed