perlapi: Include general information

Unlike other pod handling routines, autodoc requires the line following
an =head1 to be non-empty for its text to be included in the paragraph
started by the heading.  If you fail to do this, silently the text will
be omitted from perlapi.  I went through the source code, and where it
was apparent that the text was supposed to be in perlapi, deleted the
empty line so it would be, with some revisions to make more sense.

I added =cuts where I thought it best for the text to not be included.

diff --git a/gv.c b/gv.c
index d52c5c3..d8cc012 100644 (file)
--- a/gv.c
+++ b/gv.c
@@ -21,7 +21,6 @@
 
 /*
 =head1 GV Functions
-
 A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
 It is a structure that holds a pointer to a scalar, an array, a hash etc,
 corresponding to $foo, @foo, %foo.

diff --git a/hv.c b/hv.c
index 4577363..d51f95b 100644 (file)
--- a/hv.c
+++ b/hv.c
@@ -18,7 +18,6 @@
 
 /* 
 =head1 Hash Manipulation Functions
-
 A HV structure represents a Perl hash.  It consists mainly of an array
 of pointers, each of which points to a linked list of HE structures.  The
 array is indexed by the hash function of the key, so each linked list

diff --git a/mg.c b/mg.c
index e62e9e6..cf0d323 100644 (file)
--- a/mg.c
+++ b/mg.c
@@ -17,7 +17,6 @@
 
 /*
 =head1 Magical Functions
-
 "Magic" is special data attached to SV structures in order to give them
 "magical" properties.  When any Perl code tries to read from, or assign to,
 an SV marked as magical, it calls the 'get' or 'set' function associated
@@ -35,6 +34,8 @@ plus space for some flags and pointers.  For example, a tied variable has
 a MAGIC structure that contains a pointer to the object associated with the
 tie.
 
+=cut
+
 */
 
 #include "EXTERN.h"

diff --git a/mro.c b/mro.c
index ccf4bf4..76230ba 100644 (file)
--- a/mro.c
+++ b/mro.c
@@ -17,7 +17,6 @@
 
 /*
 =head1 MRO Functions
-
 These functions are related to the method resolution order of perl classes
 
 =cut

diff --git a/numeric.c b/numeric.c
index 3383cfa..e0ffafa 100644 (file)
--- a/numeric.c
+++ b/numeric.c
@@ -18,11 +18,11 @@
 /*
 =head1 Numeric functions
 
+=cut
+
 This file contains all the stuff needed by perl for manipulating numeric
 values, including such things as replacements for the OS's atof() function
 
-=cut
-
 */
 
 #include "EXTERN.h"

diff --git a/sv.c b/sv.c
index f8504d1..ec0e654 100644 (file)
--- a/sv.c
+++ b/sv.c
@@ -139,7 +139,6 @@
 /* ============================================================================
 
 =head1 Allocation and deallocation of SVs.
-
 An SV (or AV, HV, etc.) is allocated in two parts: the head (struct
 sv, av, hv...) contains type and reference count information, and for
 many types, a pointer to the body (struct xrv, xpv, xpviv...), which
@@ -164,12 +163,12 @@ slot in the arena.  SV-bodies are further described later.
 
 The following global variables are associated with arenas:
 
-    PL_sv_arenaroot    pointer to list of SV arenas
-    PL_sv_root         pointer to list of free SV structures
+ PL_sv_arenaroot     pointer to list of SV arenas
+ PL_sv_root          pointer to list of free SV structures
 
-    PL_body_arenas     head of linked-list of body arenas
-    PL_body_roots[]    array of pointers to list of free bodies of svtype
-                       arrays are indexed by the svtype needed
+ PL_body_arenas      head of linked-list of body arenas
+ PL_body_roots[]     array of pointers to list of free bodies of svtype
+                     arrays are indexed by the svtype needed
 
 A few special SV heads are not allocated from an arena, but are
 instead directly created in the interpreter structure, eg PL_sv_undef.
@@ -742,6 +741,7 @@ Deallocate the memory used by all arenas.  Note that all the individual SV
 heads and bodies within the arenas must already have been freed.
 
 =cut
+
 */
 void
 Perl_sv_free_arenas(pTHX)
@@ -11789,6 +11789,8 @@ Perl_sv_vcatpvfn_flags(pTHX_ SV *const sv, const char *const pat, const STRLEN p
 
 =head1 Cloning an interpreter
 
+=cut
+
 All the macros and functions in this section are for the private use of
 the main function, perl_clone().
 
@@ -11797,8 +11799,6 @@ During the course of a cloning, a hash table is used to map old addresses
 to new addresses.  The table is created and manipulated with the
 ptr_table_* functions.
 
-=cut
-
  * =========================================================================*/
 
 

diff --git a/toke.c b/toke.c
index 692ab11..ddb5cd4 100644 (file)
--- a/toke.c
+++ b/toke.c
@@ -23,7 +23,6 @@
 
 /*
 =head1 Lexer interface
-
 This is the lower layer of the Perl parser, managing characters and tokens.
 
 =for apidoc AmU|yy_parser *|PL_parser

diff --git a/utf8.c b/utf8.c
index f4e9a57..f802199 100644 (file)
--- a/utf8.c
+++ b/utf8.c
@@ -39,8 +39,7 @@ static const char unees[] =
 
 /*
 =head1 Unicode Support
-
-This file contains various utility functions for manipulating UTF8-encoded
+These are various utility functions for manipulating UTF8-encoded
 strings.  For the uninitiated, this is a method of representing arbitrary
 Unicode characters as a variable number of bytes, in such a way that
 characters in the ASCII range are unmodified, and a zero byte never appears