From ccfc67b7b0a9fa9e1a1cbb2090b71ea33fc44ae7 Mon Sep 17 00:00:00 2001 From: Jarkko Hietaniemi Date: Thu, 3 Jan 2002 15:57:42 +0000 Subject: [PATCH] Missed the =head1 additions. p4raw-id: //depot/perl@14041 --- XSUB.h | 6 ++++++ av.c | 4 ++++ av.h | 4 ++++ cop.h | 4 +++- cv.h | 4 ++++ doio.c | 2 ++ gv.c | 4 ++++ gv.h | 2 ++ handy.h | 14 ++++++++++++-- hv.h | 6 ++++++ intrpvar.h | 2 ++ mg.c | 4 ++++ numeric.c | 4 ++++ op.c | 6 ++++++ op.h | 2 ++ perl.c | 15 +++++++++++++++ pp.h | 2 ++ pp_sort.c | 2 ++ scope.h | 2 ++ sharedsv.c | 2 ++ sv.c | 4 ++++ sv.h | 8 ++++++++ thrdvar.h | 4 ++++ universal.c | 2 ++ utf8.c | 4 ++-- util.c | 11 +++++++++++ 26 files changed, 119 insertions(+), 5 deletions(-) diff --git a/XSUB.h b/XSUB.h index a6dfdc4..5066ee2 100644 --- a/XSUB.h +++ b/XSUB.h @@ -4,6 +4,8 @@ /* first, some documentation for xsubpp-generated items */ /* +=head1 Variables created by C and C internal functions + =for apidoc Amn|char*|CLASS Variable which is setup by C to indicate the class name for a C++ XS constructor. This is always a C. See C. @@ -98,6 +100,8 @@ handled automatically by C. /* 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 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. =for apidoc Ams||XSRETURN_EMPTY Return an empty list from an XSUB immediately. +=head1 Variables created by C and C internal functions + =for apidoc AmU||newXSproto Used by C 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 --- 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 def66b9..0d041b6 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. Deprecated, use C instead. diff --git a/cop.h b/cop.h index 9f17b2c..0040cbe 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 8e7cad6..8591f6b 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 32427eb..be27b93 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 to spawn a glob (or do the glob inside diff --git a/gv.c b/gv.c index eb7b3ba..d5f1974 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 428ab77..6dd206c 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 c792665..1acfb0d 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). #endif /* + +=head1 Character classes + =for apidoc Am|bool|isALNUM|char ch Returns a boolean indicating whether the C C 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 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 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 function. diff --git a/hv.h b/hv.h index 3a3d867..2601259 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 pointer where a C 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, C. diff --git a/intrpvar.h b/intrpvar.h index c46c8c1..3d08143 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 4369e4a..c089c8b 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 ba2f5b8..0c88db1 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 047fe6d..2cd4d7f 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 is a constant sub eligible for inlining. returns the constant diff --git a/op.h b/op.h index 3348435..2bfdced 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. Returns C, C or C for void, scalar or list context, diff --git a/perl.c b/perl.c index a96fbbd..e7f7ad6 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. @@ -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 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 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 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 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. @@ -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 the file named by the string argument. It is diff --git a/pp.h b/pp.h index 1d9a933..ac64fe2 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. See C and C. diff --git a/pp_sort.c b/pp_sort.c index e758984..582bd4e 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 edf7ffe..f0abb72 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 and L. diff --git a/sharedsv.c b/sharedsv.c index e4b6e0f..f0cba10 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 ba51738..ce4b8bf 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 a80989a..7c07988 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 in the C enum. Test these flags with the C 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 on an SV if it has 'get' magic. This macro evaluates its argument more than once. @@ -1161,6 +1167,8 @@ Like C, but does any set magic required afterwards. =for apidoc Am|void|SvSetMagicSV_nosteal|SV* dsv|SV* ssv Like C, 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 e517c1e..b23dafc 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 868fe55..8fc7d69 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 2b5ae42..93c1128 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 to the end diff --git a/util.c b/util.c index 1d2048b..a8e7553 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 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 -- 1.8.3.1