This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Missed the =head1 additions.
authorJarkko Hietaniemi <jhi@iki.fi>
Thu, 3 Jan 2002 15:57:42 +0000 (15:57 +0000)
committerJarkko Hietaniemi <jhi@iki.fi>
Thu, 3 Jan 2002 15:57:42 +0000 (15:57 +0000)
p4raw-id: //depot/perl@14041

26 files changed:
XSUB.h
av.c
av.h
cop.h
cv.h
doio.c
gv.c
gv.h
handy.h
hv.h
intrpvar.h
mg.c
numeric.c
op.c
op.h
perl.c
pp.h
pp_sort.c
scope.h
sharedsv.c
sv.c
sv.h
thrdvar.h
universal.c
utf8.c
util.c

diff --git a/XSUB.h b/XSUB.h
index a6dfdc4..5066ee2 100644 (file)
--- 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 8a4f855..fdcdb82 100644 (file)
--- a/av.c
+++ b/av.c
  * 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 def66b9..0d041b6 100644 (file)
--- 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 9f17b2c..0040cbe 100644 (file)
--- 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 8e7cad6..8591f6b 100644 (file)
--- 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 32427eb..be27b93 100644 (file)
--- 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 eb7b3ba..d5f1974 100644 (file)
--- a/gv.c
+++ b/gv.c
  * 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 428ab77..6dd206c 100644 (file)
--- 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 c792665..1acfb0d 100644 (file)
--- a/handy.h
+++ b/handy.h
 #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 3a3d867..2601259 100644 (file)
--- 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>.
 
index c46c8c1..3d08143 100644 (file)
@@ -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 4369e4a..c089c8b 100644 (file)
--- a/mg.c
+++ b/mg.c
  * 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"
index ba2f5b8..0c88db1 100644 (file)
--- a/numeric.c
+++ b/numeric.c
  * 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 047fe6d..2cd4d7f 100644 (file)
--- 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 3348435..2bfdced 100644 (file)
--- 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 a96fbbd..e7f7ad6 100644 (file)
--- 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 1d9a933..ac64fe2 100644 (file)
--- 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>.
index e758984..582bd4e 100644 (file)
--- 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 edf7ffe..f0abb72 100644 (file)
--- 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>.
index e4b6e0f..f0cba10 100644 (file)
@@ -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 ba51738..ce4b8bf 100644 (file)
--- 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 a80989a..7c07988 100644 (file)
--- 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
index e517c1e..b23dafc 100644 (file)
--- a/thrdvar.h
+++ b/thrdvar.h
@@ -1,3 +1,7 @@
+/*
+=head1 Global Variables
+*/
+
 /***********************************************/
 /* Global only to current thread               */
 /***********************************************/
index 868fe55..8fc7d69 100644 (file)
@@ -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 2b5ae42..93c1128 100644 (file)
--- 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 1d2048b..a8e7553 100644 (file)
--- 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