diff options
| -rw-r--r-- | XSUB.h | 4 | ||||
| -rw-r--r-- | av.c | 2 | ||||
| -rw-r--r-- | av.h | 2 | ||||
| -rw-r--r-- | cop.h | 8 | ||||
| -rw-r--r-- | cv.h | 11 | ||||
| -rw-r--r-- | doio.c | 2 | ||||
| -rw-r--r-- | dump.c | 4 | ||||
| -rw-r--r-- | gv.c | 2 | ||||
| -rw-r--r-- | gv.h | 2 | ||||
| -rw-r--r-- | handy.h | 50 | ||||
| -rw-r--r-- | hv.c | 4 | ||||
| -rw-r--r-- | hv.h | 6 | ||||
| -rw-r--r-- | inline.h | 7 | ||||
| -rw-r--r-- | locale.c | 2 | ||||
| -rw-r--r-- | malloc.c | 1 | ||||
| -rw-r--r-- | mathoms.c | 8 | ||||
| -rw-r--r-- | mg.c | 5 | ||||
| -rw-r--r-- | mro_core.c | 2 | ||||
| -rw-r--r-- | numeric.c | 2 | ||||
| -rw-r--r-- | op.c | 2 | ||||
| -rw-r--r-- | op.h | 2 | ||||
| -rw-r--r-- | pad.c | 2 | ||||
| -rw-r--r-- | patchlevel.h | 2 | ||||
| -rw-r--r-- | perl.c | 12 | ||||
| -rw-r--r-- | perl.h | 32 | ||||
| -rw-r--r-- | perlio.h | 4 | ||||
| -rw-r--r-- | pod/perlapio.pod | 2 | ||||
| -rw-r--r-- | pod/perlcall.pod | 3 | ||||
| -rw-r--r-- | pod/perlfilter.pod | 1 | ||||
| -rw-r--r-- | pod/perlguts.pod | 7 | ||||
| -rw-r--r-- | pod/perlhacktips.pod | 2 | ||||
| -rw-r--r-- | pod/perlmroapi.pod | 1 | ||||
| -rw-r--r-- | pp_ctl.c | 2 | ||||
| -rw-r--r-- | pp_sort.c | 3 | ||||
| -rw-r--r-- | pp_sys.c | 2 | ||||
| -rw-r--r-- | regcomp.c | 1 | ||||
| -rw-r--r-- | scope.c | 2 | ||||
| -rw-r--r-- | sv.c | 8 | ||||
| -rw-r--r-- | sv.h | 6 | ||||
| -rw-r--r-- | t/porting/customized.dat | 4 | ||||
| -rw-r--r-- | universal.c | 2 | ||||
| -rw-r--r-- | util.c | 21 | ||||
| -rw-r--r-- | util.h | 2 | ||||
| -rw-r--r-- | vutil.c | 2 |
44 files changed, 148 insertions, 103 deletions
@@ -14,7 +14,7 @@ /* first, some documentation for xsubpp-generated items */ /* -=head1 C<xsubpp> variables and internal functions +=for apidoc_section XS =for apidoc Amn|char*|CLASS Variable which is setup by C<xsubpp> to indicate the @@ -258,8 +258,6 @@ Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>. =for apidoc Amns||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|char* name|XSUBADDR_t f|char* filename|const char *proto Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to the subs. @@ -16,7 +16,7 @@ */ /* -=head1 Array Manipulation Functions +=for apidoc_section AV Handling */ #include "EXTERN.h" @@ -44,8 +44,6 @@ Null AV pointer. (deprecated - use C<(AV *)NULL> instead) -=head1 Array Manipulation Functions - =for apidoc Am|int|AvFILL|AV* av Same as C<av_top_index()> or C<av_tindex()>. @@ -481,10 +481,6 @@ struct cop { #define CopHINTHASH_set(c,h) ((c)->cop_hints_hash = (h)) /* -=head1 COP Hint Reading -*/ - -/* =for apidoc Am|SV *|cop_hints_fetch_pvn|const COP *cop|const char *keypv|STRLEN keylen|U32 hash|U32 flags Look up the hint entry in the cop C<cop> with the key specified by @@ -942,10 +938,6 @@ struct context { #define CXINC (cxstack_ix < cxstack_max ? ++cxstack_ix : (cxstack_ix = cxinc())) /* -=head1 "Gimme" Values -*/ - -/* =for apidoc AmnU||G_SCALAR Used to indicate scalar context. See C<L</GIMME_V>>, C<L</GIMME>>, and L<perlcall>. @@ -16,18 +16,16 @@ struct xpvcv { }; /* -=head1 Handy Values +=head1 CV Handling + +This section documents functions to manipulate CVs which are code-values, +meaning subroutines. For more information, see L<perlguts>. =for apidoc ADmnU||Nullcv Null CV pointer. (deprecated - use C<(CV *)NULL> instead) -=head1 CV Manipulation Functions - -This section documents functions to manipulate CVs which are code-values, -or subroutines. For more information, see L<perlguts>. - =for apidoc Am|HV*|CvSTASH|CV* cv Returns the stash of the CV. A stash is the symbol table hash, containing the package-scoped variables in the package where the subroutine was defined. @@ -255,7 +253,6 @@ CvNAME_HEK(CV *sv) ) /* -=head1 CV reference counts and CvOUTSIDE =for apidoc m|bool|CvWEAKOUTSIDE|CV *cv @@ -3252,7 +3252,7 @@ Perl_do_shmio(pTHX_ I32 optype, SV **mark, SV **sp) #endif /* SYSV IPC */ /* -=head1 IO Functions +=for apidoc_section Input/Output =for apidoc start_glob @@ -528,10 +528,6 @@ Perl_sv_peek(pTHX_ SV *sv) return SvPV_nolen(t); } -/* -=head1 Debugging Utilities -*/ - void Perl_dump_indent(pTHX_ I32 level, PerlIO *file, const char* pat, ...) { @@ -20,7 +20,7 @@ */ /* -=head1 GV Functions +=head1 GV Handling 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. @@ -72,7 +72,7 @@ struct gp { #define GvNAMELEN(gv) GvNAMELEN_get(gv) /* -=head1 GV Functions +=for apidoc_section GV Handling =for apidoc Am|SV*|GvSV|GV* gv @@ -18,16 +18,40 @@ # define Null(type) ((type)NULL) /* -=head1 Handy Values - +=for apidoc_section String Handling =for apidoc AmnU||Nullch Null character pointer. (No longer available when C<PERL_CORE> is defined.) +=for apidoc_section SV Handling =for apidoc AmnU||Nullsv Null SV pointer. (No longer available when C<PERL_CORE> is defined.) =cut + +Below are signatures of functions from config.h which can't easily be gleaned +from it, and are very unlikely to change + +=for apidoc_section Signals +=for apidoc Am|int|Sigsetjmp|jmp_buf env|int savesigs +=for apidoc Am|void|Siglongjmp|jmp_buf env|int val + +=for apidoc_section Filesystem configuration values +=for apidoc Am|void *|FILE_ptr|FILE * f +=for apidoc Am|Size_t|FILE_cnt|FILE * f +=for apidoc Am|void *|FILE_base|FILE * f +=for apidoc Am|Size_t|FILE_bufsiz + +=for apidoc_section String Handling +=for apidoc Am|token|CAT2|token x|token y +=for apidoc Am|string|STRINGIFY|token x + +=for apidoc_section Numeric Functions +=for apidoc Am|double|Drand01|double x +=for apidoc Am|void|seedDrand01|Rand_seed_t x +=for apidoc Am|char *|Gconvert|double x|Size_t n|bool t|char * b + +=cut */ # define Nullch Null(char*) @@ -98,6 +122,7 @@ Null SV pointer. (No longer available when C<PERL_CORE> is defined.) #endif /* +=for apidoc_section Casting =for apidoc Am|bool|cBOOL|bool expr Cast-to-bool. A simple S<C<(bool) I<expr>>> cast may not do the right thing: @@ -279,6 +304,7 @@ typedef U64TYPE U64; #define nBIT_UMAX(n) nBIT_MASK(n) /* +=for apidoc_section Compiler directives =for apidoc Am|void|__ASSERT_|bool expr This is a helper macro to avoid preprocessor issues, replaced by nothing @@ -300,7 +326,7 @@ detects that and gets all excited. */ #endif /* -=head1 SV Manipulation Functions +=for apidoc_section SV Handling =for apidoc Ama|SV*|newSVpvs|"literal string" Like C<newSVpvn>, but takes a literal string instead of a @@ -342,7 +368,7 @@ string/length pair. Like C<sv_setref_pvn>, but takes a literal string instead of a string/length pair. -=head1 Memory Management +=for apidoc_section String Handling =for apidoc Ama|char*|savepvs|"literal string" Like C<savepvn>, but takes a literal string instead of a @@ -352,13 +378,13 @@ string/length pair. A version of C<savepvs()> which allocates the duplicate string in memory which is shared between threads. -=head1 GV Functions +=for apidoc_section GV Handling =for apidoc Am|HV*|gv_stashpvs|"name"|I32 create Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair. -=head1 Hash Manipulation Functions +=for apidoc_section HV Handling =for apidoc Am|SV**|hv_fetchs|HV* tb|"key"|I32 lval Like C<hv_fetch>, but takes a literal string instead of a @@ -380,7 +406,7 @@ a string/length pair. */ /* -=head1 Handy Values +=for apidoc_section String Handling =for apidoc Amu|pair|STR_WITH_LEN|"literal string" @@ -455,6 +481,7 @@ Perl_xxx(aTHX_ ...) form for any API calls where it's used. PERL_VERSION_PATCH) /* +=for apidoc_section Versioning =for apidoc AmR|bool|PERL_VERSION_EQ|const U8 major|const U8 minor|const U8 patch Returns whether or not the perl currently being compiled has the specified @@ -529,7 +556,7 @@ becomes # define PERL_VERSION_GT(j,n,p) (! PERL_VERSION_LE(j,n,p)) /* -=head1 Miscellaneous Functions +=for apidoc_section String Handling =for apidoc Am|bool|strNE|char* s1|char* s2 Test two C<NUL>-terminated strings to see if they are different. Returns true @@ -1153,7 +1180,7 @@ C<isIDCONT_LC_utf8>, and C<isIDCONT_LC_utf8_safe>. =for apidoc Amh|bool|isIDCONT_LC_uvchr|int ch =for apidoc Amh|bool|isIDCONT_LC_utf8_safe|U8 * s| U8 *end -=head1 Miscellaneous Functions +=for apidoc_section Numeric Functions =for apidoc Am|U8|READ_XDIGIT|char str* Returns the value of an ASCII-range hex digit and advances the string pointer. @@ -1340,6 +1367,7 @@ patched there. The file as of this writing is cpan/Devel-PPPort/parts/inc/misc /* void below because that's the best fit, and works for Devel::PPPort +=for apidoc_section Integer configuration values =for apidoc AmnU|void|WIDEST_UTYPE Yields the widest unsigned integer type on the platform, currently either @@ -2485,6 +2513,7 @@ The XSUB-writer's interface to the C C<free> function. This should B<ONLY> be used on memory obtained using L</"Newx"> and friends. +=for apidoc_section String Handling =for apidoc Am|void|Move|void* src|void* dest|int nitems|type The XSUB-writer's interface to the C C<memmove> function. The C<src> is the source, C<dest> is the destination, C<nitems> is the number of items, and @@ -2517,6 +2546,7 @@ Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call optimise. +=for apidoc_section Utility Functions =for apidoc Am|void|StructCopy|type *src|type *dest|type This is an architecture-independent macro to copy one structure to another. @@ -2731,7 +2761,7 @@ void Perl_mem_log_del_sv(const SV *sv, const char *filename, const int linenumbe #define StructCopy(s,d,t) (*((t*)(d)) = *((t*)(s))) /* -=head1 Handy Values +=for apidoc_section Utility Functions =for apidoc Am|STRLEN|C_ARRAY_LENGTH|void *a @@ -17,7 +17,7 @@ */ /* -=head1 Hash Manipulation Functions +=head1 HV Handling 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 @@ -3731,6 +3731,7 @@ Perl_refcounted_he_inc(pTHX_ struct refcounted_he *he) } /* +=for apidoc_section COP Hint Hashes =for apidoc cop_fetch_label Returns the label attached to a cop, and stores its length in bytes into @@ -3810,6 +3811,7 @@ Perl_cop_store_label(pTHX_ COP *const cop, const char *label, STRLEN len, } /* +=for apidoc_section HV Handling =for apidoc hv_assert Check that a hash is in an internally consistent state. @@ -140,22 +140,18 @@ struct xpvhv { }; /* -=head1 Hash Manipulation Functions +=for apidoc_section HV Handling =for apidoc AmnU||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 ADmnU||Nullhv Null HV pointer. (deprecated - use C<(HV *)NULL> instead) -=head1 Hash Manipulation Functions - =for apidoc Am|char*|HvNAME|HV* stash Returns the package name of a stash, or C<NULL> if C<stash> isn't a stash. See C<L</SvSTASH>>, C<L</CvSTASH>>. @@ -40,6 +40,7 @@ SOFTWARE. /* ------------------------------- av.h ------------------------------- */ /* +=for apidoc_section AV Handling =for apidoc av_count Returns the number of elements in the array C<av>. This is the true length of the array, including any undefined elements. It is always the same as @@ -1876,7 +1877,7 @@ Perl_utf8_to_uvchr_buf_helper(pTHX_ const U8 *s, const U8 *send, STRLEN *retlen) /* ------------------------------- perl.h ----------------------------- */ /* -=head1 Miscellaneous Functions +=for apidoc_section Utility Functions =for apidoc is_safe_syscall @@ -2449,7 +2450,7 @@ Perl_cx_popgiven(pTHX_ PERL_CONTEXT *cx) /* ------------------ util.h ------------------------------------------- */ /* -=head1 Miscellaneous Functions +=for apidoc_section String Handling =for apidoc foldEQ @@ -2505,6 +2506,7 @@ Perl_foldEQ_latin1(const char *s1, const char *s2, I32 len) } /* +=for apidoc_section Locales =for apidoc foldEQ_locale Returns true if the leading C<len> bytes of the strings C<s1> and C<s2> are the @@ -2532,6 +2534,7 @@ Perl_foldEQ_locale(const char *s1, const char *s2, I32 len) } /* +=for apidoc_section String Handling =for apidoc my_strnlen The C library C<strnlen> if available, or a Perl implementation of it. @@ -2281,7 +2281,7 @@ S_win32_setlocale(pTHX_ int category, const char* locale) /* -=head1 Locale-related functions and macros +=for apidoc_section Locales =for apidoc Perl_setlocale @@ -1225,6 +1225,7 @@ S_adjust_size_and_find_bucket(size_t *nbytes_p) /* These have the same interfaces as the C lib ones, so are considered documented +=for apidoc_section Memory Management =for apidoc malloc =for apidoc calloc =for apidoc realloc @@ -50,7 +50,7 @@ * * Some blurb for perlapi.pod: -=head1 Obsolete backwards compatibility functions + head1 Obsolete backwards compatibility functions Some of these are also deprecated. You can exclude these from your compiled Perl by adding this option to Configure: @@ -85,6 +85,7 @@ Perl_ref(pTHX_ OP *o, I32 type) } /* +=for apidoc_section SV Handling =for apidoc sv_unref Unsets the RV status of the SV, and decrements the reference count of @@ -605,6 +606,7 @@ Perl_gv_efullname3(pTHX_ SV *sv, const GV *gv, const char *prefix) } /* +=for apidoc_section GV Handling =for apidoc gv_fetchmethod See L</gv_fetchmethod_autoload>. @@ -702,6 +704,7 @@ Perl_is_utf8_string_loc(const U8 *s, const STRLEN len, const U8 **ep) } /* +=for apidoc_section SV Handling =for apidoc sv_nolocking Dummy routine which "locks" an SV when there is no locking module present. @@ -819,6 +822,7 @@ Perl_sv_usepvn(pTHX_ SV *sv, char *ptr, STRLEN len) } /* +=for apidoc_section Pack and Unpack =for apidoc unpack_str The engine implementing C<unpack()> Perl function. Note: parameters C<strbeg>, @@ -1115,6 +1119,7 @@ Perl_sv_2bool(pTHX_ SV *const sv) /* +=for apidoc_section Custom Operators =for apidoc custom_op_name Return the name for a given custom op. This was once used by the C<OP_NAME> macro, but is no longer: it has only been kept for compatibility, and @@ -1177,6 +1182,7 @@ ASCII_TO_NEED(const UV enc, const UV ch) } /* +=for apidoc_section Unicode Support =for apidoc is_utf8_char Tests if some arbitrary number of bytes begins in a valid UTF-8 @@ -16,7 +16,7 @@ */ /* -=head1 Magical Functions +=head1 Magic "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 @@ -846,6 +846,7 @@ S_fixup_errno_string(pTHX_ SV* sv) } /* +=for apidoc_section Errno =for apidoc sv_string_from_errnum Generates the message string describing an OS error and returns it as @@ -1909,6 +1910,7 @@ Perl_magic_setnkeys(pTHX_ SV *sv, MAGIC *mg) } /* +=for apidoc_section Magic =for apidoc magic_methcall Invoke a magic method (like FETCH). @@ -3639,6 +3641,7 @@ S_unwind_handler_stack(pTHX_ const void *p) } /* +=for apidoc_section Magic =for apidoc magic_sethint Triggered by a store to C<%^H>, records the key/value pair to diff --git a/mro_core.c b/mro_core.c index 1fc7c7ca9d..378c738c7a 100644 --- a/mro_core.c +++ b/mro_core.c @@ -19,7 +19,7 @@ */ /* -=head1 MRO Functions +=head1 MRO These functions are related to the method resolution order of perl classes Also see L<perlmroapi>. @@ -16,7 +16,7 @@ */ /* -=head1 Numeric functions +=for apidoc_section Numeric Functions =cut @@ -8877,7 +8877,7 @@ Perl_utilize(pTHX_ int aver, I32 floor, OP *version, OP *idop, OP *arg) } /* -=head1 Embedding Functions +=for apidoc_section Embedding and Interpreter Cloning =for apidoc load_module @@ -70,7 +70,7 @@ typedef PERL_BITFIELD16 Optype; #define OP_GIMME_REVERSE(flags) ((flags) & G_WANT) /* -=head1 "Gimme" Values +=for apidoc_section Callback Functions =for apidoc Amn|U32|GIMME_V The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>, @@ -272,7 +272,7 @@ Perl_pad_new(pTHX_ int flags) /* -=head1 Embedding Functions +=for apidoc_section Embedding and Interpreter Cloning =for apidoc cv_undef diff --git a/patchlevel.h b/patchlevel.h index a8e3319eff..452605c586 100644 --- a/patchlevel.h +++ b/patchlevel.h @@ -9,7 +9,7 @@ */ /* -=head1 Handy Values +=for apidoc_section Versioning =for apidoc AmDnU|U8|PERL_REVISION The major number component of the perl interpreter currently being compiled or @@ -177,7 +177,7 @@ perl_alloc_using(struct IPerlMem* ipM, struct IPerlMem* ipMS, #else /* -=head1 Embedding Functions +=for apidoc_section Embedding and Interpreter Cloning =for apidoc perl_alloc @@ -2742,7 +2742,7 @@ S_run_body(pTHX_ I32 oldscope) } /* -=head1 SV Manipulation Functions +=for apidoc_section SV Handling =for apidoc get_sv @@ -2768,7 +2768,7 @@ Perl_get_sv(pTHX_ const char *name, I32 flags) } /* -=head1 Array Manipulation Functions +=for apidoc_section AV Handling =for apidoc get_av @@ -2798,7 +2798,7 @@ Perl_get_av(pTHX_ const char *name, I32 flags) } /* -=head1 Hash Manipulation Functions +=for apidoc_section HV Handling =for apidoc get_hv @@ -2825,7 +2825,7 @@ Perl_get_hv(pTHX_ const char *name, I32 flags) } /* -=head1 CV Manipulation Functions +=for apidoc_section CV Handling =for apidoc get_cvn_flags @@ -3271,7 +3271,7 @@ Perl_eval_pv(pTHX_ const char *p, I32 croak_on_error) /* Require a module. */ /* -=head1 Embedding Functions +=for apidoc_section Embedding and Interpreter Cloning =for apidoc require_pv @@ -84,6 +84,7 @@ /* <--- here ends the logic shared by perl.h and makedef.pl */ /* +=for apidoc_section Compiler directives =for apidoc AmnUu|void|EXTERN_C When not compiling using C++, expands to nothing. Otherwise is used in a declaration of a function to indicate the function @@ -408,8 +409,6 @@ Otherwise ends a section of code already begun by a C<L</START_EXTERN_C>>. * but we cannot quite get rid of, such as "ax" in PPCODE+noargs xsubs, * or variables/arguments that are used only in certain configurations. -=head1 Miscellaneous Functions - =for apidoc Am||PERL_UNUSED_ARG|void x This is used to suppress compiler warnings that a parameter to a function is not used. This situation can arise, for example, when a parameter is needed @@ -633,8 +632,7 @@ __typeof__ and nothing else. #endif /* -=head1 Miscellaneous Functions - +=for apidoc_section Compiler directives =for apidoc AmnUu|void|STMT_START STMT_START { statements; } STMT_END; @@ -1076,6 +1074,7 @@ EXTERN_C int usleep(unsigned int); # endif /* +=for apidoc_section Integer configuration values =for apidoc Am||INTMAX_C|number Returns a token the C compiler recognizes for the constant C<number> of the widest integer type on the machine. For example, if the machine has C<long @@ -1585,6 +1584,7 @@ any magic. #endif /* +=for apidoc_section SV Handling =for apidoc Amn|SV *|DEFSV Returns the SV associated with C<$_> @@ -1806,8 +1806,7 @@ Localize C<$_>. See L<perlguts/Localizing changes>. * longer need that. XS modules can (and do) use this name, so it must remain * a part of the API that's visible to modules. -=head1 Miscellaneous Functions - +=for apidoc_section String Handling =for apidoc ATmD|int|my_sprintf|NN char *buffer|NN const char *pat|... Do NOT use this due to the possibility of overflowing C<buffer>. Instead use @@ -2631,7 +2630,7 @@ extern long double Perl_my_frexpl(long double x, int *e); #endif /* -=head1 Numeric functions +=for apidoc_section Integer configuration values =for apidoc AmnUh||PERL_INT_MIN =for apidoc AmnUh||PERL_LONG_MAX @@ -2650,6 +2649,8 @@ extern long double Perl_my_frexpl(long double x, int *e); =for apidoc AmnUh||PERL_USHORT_MAX =for apidoc AmnUh||PERL_USHORT_MIN =for apidoc AmnUh||PERL_QUAD_MIN +=for apidoc_section Floating point configuration values + =for apidoc AmnU||PERL_INT_MAX This and C<PERL_INT_MIN>, @@ -3068,7 +3069,7 @@ typedef struct padname PADNAME; #endif /* -=head1 Miscellaneous Functions +=for apidoc_section Embedding and Interpreter Cloning =for apidoc Am|void|PERL_SYS_INIT|int *argc|char*** argv Provides system-specific tune up of the C runtime environment necessary to @@ -3668,7 +3669,7 @@ EXTERN_C int perl_tsa_mutex_unlock(perl_mutex* mutex) #endif /* -=head1 Miscellaneous Functions +=for apidoc_section Compiler directives =for apidoc AmU|bool|LIKELY|const bool expr @@ -6192,7 +6193,7 @@ typedef struct am_table_short AMTS; cBOOL(PL_hints & (HINT_LOCALE|HINT_LOCALE_PARTIAL)) /* -=head1 Locale-related functions and macros +=for apidoc_section Locales =for apidoc Amn|bool|IN_LOCALE @@ -6460,7 +6461,7 @@ the plain locale pragma without a parameter (S<C<use locale>>) is in effect. * operations used by Perl, namely the decimal point, and even the thousands * separator.) -=head1 Locale-related functions and macros +=for apidoc_section Locales =for apidoc Amn|void|DECLARATION_FOR_LC_NUMERIC_MANIPULATION @@ -6753,7 +6754,7 @@ cannot have changed since the precalculation. /* -=head1 Numeric functions +=for apidoc_section Numeric Functions =for apidoc AmTR|NV|Strtod|NN const char * const s|NULLOK char ** e @@ -7081,7 +7082,7 @@ EXTERN_C int flock(int fd, int op); #define IS_NUMBER_TRAILING 0x40 /* number has trailing trash */ /* -=head1 Numeric functions +=for apidoc_section Numeric Functions =for apidoc AmdR|bool|GROK_NUMERIC_RADIX|NN const char **sp|NN const char *send @@ -7190,6 +7191,7 @@ extern void moncontrol(int); #define PERL_UNICODE_UTF8CACHEASSERT 'a' /* +=for apidoc_section Signals =for apidoc Amn|U32|PERL_SIGNALS_UNSAFE_FLAG If this bit in C<PL_signals> is set, the system is uing the pre-Perl 5.8 unsafe signals. See L<perlrun/PERL_SIGNALS> and L<perlipc/Deferred Signals @@ -7200,7 +7202,7 @@ unsafe signals. See L<perlrun/PERL_SIGNALS> and L<perlipc/Deferred Signals #define PERL_SIGNALS_UNSAFE_FLAG 0x0001 /* -=head1 Numeric functions +=for apidoc_section Numeric Functions =for apidoc Am|int|PERL_ABS|int @@ -7232,7 +7234,7 @@ so no C<x++>. /* -=head1 Miscellaneous Functions +=for apidoc_section Utility Functions =for apidoc Am|bool|IS_SAFE_SYSCALL|NN const char *pv|STRLEN len|NN const char *what|NN const char *op_name @@ -63,6 +63,10 @@ typedef PerlIOl *PerlIO; #define PerlIO PerlIO #define PERLIO_LAYERS 1 +/* +=for apidoc_section Input/Output +=cut +*/ /* PERLIO_FUNCS_CONST is now on by default for efficiency, PERLIO_FUNCS_CONST can be removed 1 day once stable & then PerlIO vtables are permanently RO */ #ifdef PERLIO_FUNCS_CONST diff --git a/pod/perlapio.pod b/pod/perlapio.pod index f7509009bb..66add53e4d 100644 --- a/pod/perlapio.pod +++ b/pod/perlapio.pod @@ -68,6 +68,8 @@ perlapio - perl's IO abstraction interface. const char *layers); void PerlIO_debug(const char *fmt,...); +=for apidoc_section Input/Output + =for apidoc Amh|int |PerlIO_apply_layers|PerlIO *f|const char *mode|const char *layers =for apidoc Amh|int |PerlIO_binmode|PerlIO *f|int ptype|int imode|const char *layers =for apidoc ATmh|int |PerlIO_canset_cnt|PerlIO *f diff --git a/pod/perlcall.pod b/pod/perlcall.pod index c340716653..089c39785f 100644 --- a/pod/perlcall.pod +++ b/pod/perlcall.pod @@ -121,6 +121,8 @@ been warned. =head1 FLAG VALUES +=for apidoc_section Callback Functions + The C<flags> parameter in all the I<call_*> functions is one of G_VOID, G_SCALAR, or G_ARRAY, which indicate the call context, OR'ed together with a bit mask of any combination of the other G_* symbols defined below. @@ -993,6 +995,7 @@ equivalent of C<$@>. We use a local temporary, C<err_tmp>, since C<ERRSV> is a macro that calls a function, and C<SvTRUE(ERRSV)> would end up calling that function multiple times. +=for apidoc_section Callback Functions =for apidoc Amnh|GV *|PL_errgv =item 3. diff --git a/pod/perlfilter.pod b/pod/perlfilter.pod index 0744e29f8d..6b15eccf95 100644 --- a/pod/perlfilter.pod +++ b/pod/perlfilter.pod @@ -294,6 +294,7 @@ becomes M.) 1; +=for apidoc_section Source Filters =for apidoc filter_add =for apidoc filter_read diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 3b1b9d5421..4af6067882 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -548,6 +548,7 @@ is only valid for the duration of a single perl process. See L</Understanding the Magic of Tied Hashes and Arrays> for more information on how to use the hash access functions on tied hashes. +=for apidoc_section HV Handling =for apidoc Amh|void|PERL_HASH|U32 hash|char *key|STRLEN klen =head2 Hash API Extensions @@ -2408,6 +2409,7 @@ The first character could be 'p' for a B<p>rototype, 'a' for B<a>rgument, or 'd' for B<d>eclaration, so we have C<pTHX>, C<aTHX> and C<dTHX>, and their variants. +=for apidoc_section Concurrency =for apidoc Amnh||aTHX =for apidoc Amnh||aTHX_ =for apidoc Amnh||dTHX @@ -2663,6 +2665,7 @@ following macros for portability NVff NV %f-like NVgf NV %g-like +=for apidoc_section Formats =for apidoc Amnh||IVdf =for apidoc Amnh||UVuf =for apidoc Amnh||UVof @@ -2750,6 +2753,9 @@ UTF-8 in order to get good results and avoid Wide-character warnings. One way to do this for typical filehandles is to invoke perl with the C<-C>> parameter. (See L<perlrun/-C [numberE<sol>list]>. +=for apidoc_section Formats +=cut + =head2 Formatted Printing of C<Size_t> and C<SSize_t> The most general way to do this is to cast them to a UV or IV, and @@ -2779,6 +2785,7 @@ use the follow macros to do it right. PTR2NV(pointer) INT2PTR(pointertotype, integer) +=for apidoc_section Casting =for apidoc Amh|void *|INT2PTR|type|int value =for apidoc Amh|UV|PTR2UV|void * =for apidoc Amh|IV|PTR2IV|void * diff --git a/pod/perlhacktips.pod b/pod/perlhacktips.pod index 7f412e4afa..769c2f6714 100644 --- a/pod/perlhacktips.pod +++ b/pod/perlhacktips.pod @@ -671,7 +671,7 @@ library functions instead. In this case C<memchr> can be used to see if C<c> is in C<"list"> and works even if C<c> is C<NUL>. These functions need an additional parameter to give the string length. In the case of literal string parameters, perl has defined macros that -calculate the length for you. See L<perlapi/Miscellaneous Functions>. +calculate the length for you. See L<perlapi/String Handling>. =item * diff --git a/pod/perlmroapi.pod b/pod/perlmroapi.pod index c585441fc9..e2dbefd94e 100644 --- a/pod/perlmroapi.pod +++ b/pod/perlmroapi.pod @@ -79,6 +79,7 @@ stash, and a pointer to your C<mro_alg> structure: meta = HvMROMETA(stash); private_sv = MRO_GET_PRIVATE_DATA(meta, &my_mro_alg); +=for apidoc_section MRO =for apidoc mro_get_private_data To set your private value, call C<Perl_mro_set_private_data()>: @@ -1846,7 +1846,7 @@ PP(pp_xor) /* -=head1 CV Manipulation Functions +=for apidoc_section CV Handling =for apidoc caller_cx @@ -541,7 +541,7 @@ S_sortsv_flags_impl(pTHX_ gptr *base, size_t nmemb, SVCOMPARE_t cmp, U32 flags) } /* -=head1 SV Manipulation Functions +=for apidoc_section SV Handling =for apidoc sortsv_flags @@ -669,7 +669,6 @@ sortsv_cmp_locale_desc(pTHX_ gptr *base, size_t nmemb, U32 flags) #endif /* -=head1 Array Manipulation Functions =for apidoc sortsv @@ -1293,7 +1293,7 @@ PP(pp_sselect) /* -=head1 GV Functions +=for apidoc_section GV Handling =for apidoc setdefout @@ -21859,6 +21859,7 @@ Perl_regfree_internal(pTHX_ REGEXP * const rx) #define SAVEPVN(p, n) ((p) ? savepvn(p, n) : NULL) /* +=for apidoc_section REGEXP Functions =for apidoc re_dup_guts Duplicate a regexp. @@ -316,7 +316,7 @@ Perl_save_set_svflags(pTHX_ SV* sv, U32 mask, U32 val) /* -=head1 GV Functions +=for apidoc_section GV Handling =for apidoc save_gp @@ -130,8 +130,7 @@ static const char S_destroy[] = "DESTROY"; /* ============================================================================ -=head1 Allocation and deallocation of SVs. - +=for apidoc_section SV Handling 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 @@ -409,7 +408,7 @@ S_del_sv(pTHX_ SV *p) /* -=head1 SV Manipulation Functions +=for apidoc_section SV Handling =for apidoc sv_add_arena @@ -13486,7 +13485,7 @@ Perl_sv_vcatpvfn_flags(pTHX_ SV *const sv, const char *const pat, const STRLEN p /* ========================================================================= -=head1 Cloning an interpreter +=for apidoc_section Embedding and Interpreter Cloning =cut @@ -16345,6 +16344,7 @@ Perl_varname(pTHX_ const GV *const gv, const char gvtype, PADOFFSET targ, /* +=apidoc_section Warning and Dieing =for apidoc find_uninit_var Find the name of the undefined variable (if any) that caused the operator @@ -269,7 +269,7 @@ struct p5rx { #undef _SV_HEAD_UNION /* ensure no pollution */ /* -=head1 SV Manipulation Functions +=for apidoc_section SV Handling =for apidoc Am|U32|SvREFCNT|SV* sv Returns the value of the object's reference count. Exposed @@ -2095,7 +2095,7 @@ incremented. /* the following macros update any magic values this C<sv> is associated with */ /* -=head1 Magical Functions +=head1 Magic =for apidoc Am|void|SvGETMAGIC|SV* sv Invokes C<mg_get> on an SV if it has 'get' magic. For example, this @@ -2134,7 +2134,7 @@ has been loaded. Releases a mutual exclusion lock on C<sv> if a suitable module has been loaded. -=head1 SV Manipulation Functions +=for apidoc_section SV Handling =for apidoc Am|char *|SvGROW|SV* sv|STRLEN len Expands the character buffer in the SV so that it has room for the diff --git a/t/porting/customized.dat b/t/porting/customized.dat index 125430347f..395dc639e0 100644 --- a/t/porting/customized.dat +++ b/t/porting/customized.dat @@ -8,7 +8,7 @@ Digest::MD5 cpan/Digest-MD5/MD5.pm df5f0663f0f755be7eda6e3d2f008f2629246b19 Digest::MD5 cpan/Digest-MD5/MD5.xs 249bed648232192ce018f7f894ad127c3a639831 Digest::MD5 cpan/Digest-MD5/t/files.t e987329d2411ff60ad9a2bdf93fdf5f6943467e8 ExtUtils::Constant cpan/ExtUtils-Constant/t/Constant.t d5c75c41d6736a0c5897130f534af0896a7d6f4d -Filter::Util::Call pod/perlfilter.pod e9833bf4ebc51087dfee5c553e0f8a5eef67212d +Filter::Util::Call pod/perlfilter.pod 67d1ea264f5fe88e9422976e2a903bf3d1671f6d Locale::Maketext::Simple cpan/Locale-Maketext-Simple/lib/Locale/Maketext/Simple.pm 57ed38905791a17c150210cd6f42ead22a7707b6 Math::Complex cpan/Math-Complex/lib/Math/Complex.pm 66f28a17647e2de166909ca66e4ced26f8a0a62e Math::Complex cpan/Math-Complex/t/Complex.t 17039e03ee798539e770ea9a0d19a99364278306 @@ -31,4 +31,4 @@ Win32API::File cpan/Win32API-File/File.pm 8fd212857f821cb26648878b96e57f13bf21b9 Win32API::File cpan/Win32API-File/File.xs beb870fed4490d2faa547b4a8576b8d64d1d27c5 experimental cpan/experimental/t/basic.t cb9da8dd05b854375809872a05dd32637508d5da version cpan/version/lib/version.pm 7ef9219d1d5f1d71f08a79f3b0577df138b21b12 -version vutil.c 601cc57bbc0070ae33eab7fd2d667f20efbe15f8 +version vutil.c 7a416b6630a498e737aae03891d0873aaeb066f0 diff --git a/universal.c b/universal.c index 6797b9fb53..0cc6363b0a 100644 --- a/universal.c +++ b/universal.c @@ -120,7 +120,7 @@ S_sv_derived_from_svpvn(pTHX_ SV *sv, SV *namesv, const char * name, const STRLE } /* -=head1 SV Manipulation Functions +=for apidoc_section SV Handling =for apidoc sv_derived_from_pvn @@ -573,6 +573,7 @@ S_delimcpy_intern(char *to, const char *toend, const char *from, /* +=for apidoc_section String Handling =for apidoc delimcpy_no_escape Copy a source buffer to a destination buffer, stopping at (but not including) @@ -635,8 +636,6 @@ Perl_delimcpy(char *to, const char *toend, const char *from, const char *fromend } /* -=head1 Miscellaneous Functions - =for apidoc ninstr Find the first (leftmost) occurrence of a sequence of bytes within another @@ -705,8 +704,6 @@ Perl_ninstr(const char *big, const char *bigend, const char *little, const char } /* -=head1 Miscellaneous Functions - =for apidoc rninstr Like C<L</ninstr>>, but instead finds the final (rightmost) occurrence of a @@ -818,7 +815,6 @@ Perl_rninstr(const char *big, const char *bigend, const char *little, const char If FBMcf_TAIL, the table is created as if the string has a trailing \n. */ /* -=head1 Miscellaneous Functions =for apidoc fbm_compile @@ -1165,8 +1161,7 @@ Perl_cntrl_to_mnemonic(const U8 c) /* copy a string to a safe spot */ /* -=head1 Memory Management - +=for apidoc_section String Handling =for apidoc savepv Perl's version of C<strdup()>. Returns a pointer to a newly allocated @@ -1373,7 +1368,7 @@ Perl_form_nocontext(const char* pat, ...) #endif /* PERL_IMPLICIT_CONTEXT */ /* -=head1 Miscellaneous Functions +=for apidoc_section Display and Dump functions =for apidoc form Takes a sprintf-style format pattern and conventional @@ -1661,7 +1656,7 @@ Perl_write_to_stderr(pTHX_ SV* msv) } /* -=head1 Warning and Dieing +=for apidoc_section Warning and Dieing */ /* Common code used in dieing and warning */ @@ -2260,6 +2255,7 @@ S_env_alloc(void *current, Size_t l1, Size_t l2, Size_t l3, Size_t size) # if !defined(WIN32) && !defined(NETWARE) /* +=for apidoc_section Utility Functions =for apidoc my_setenv A wrapper for the C library L<setenv(3)>. Don't use the latter, as the perl @@ -2846,6 +2842,7 @@ dup2(int oldfd, int newfd) #ifdef HAS_SIGACTION /* +=for apidoc_section Signals =for apidoc rsignal A wrapper for the C library L<signal(2)>. Don't use the latter, as the Perl @@ -3952,6 +3949,7 @@ Perl_my_strftime(pTHX_ const char *fmt, int sec, int min, int hour, int mday, in #ifdef HAS_STRFTIME /* +=for apidoc_section Time =for apidoc my_strftime strftime(), but with a different API so that the return value is a pointer to the formatted result (which MUST be arranged to be FREED BY THE @@ -4060,7 +4058,7 @@ mini_mktime() overwrites them (dp->d_name[1] == '.' && dp->d_name[2] == '\0'))) /* -=head1 Miscellaneous Functions +=for apidoc_section Utility Functions =for apidoc getcwd_sv @@ -4968,6 +4966,7 @@ Perl_mem_log_del_sv(const SV *sv, #endif /* PERL_MEM_LOG */ /* +=for apidoc_section String Handling =for apidoc quadmath_format_valid C<quadmath_snprintf()> is very strict about its C<format> string and will @@ -6144,6 +6143,7 @@ static void atos_symbolize(atos_context* ctx, #endif /* #ifdef PERL_DARWIN */ /* +=for apidoc_section Display and Dump functions =for apidoc get_c_backtrace Collects the backtrace (aka "stacktrace") into a single linear @@ -6395,6 +6395,7 @@ Deallocates a backtrace received from get_c_bracktrace. */ /* +=for apidoc_section Display and Dump functions =for apidoc get_c_backtrace_dump Returns a SV containing a dump of C<depth> frames of the call stack, skipping @@ -37,7 +37,7 @@ #endif /* -=head1 Miscellaneous Functions +=for apidoc_section String Handling =for apidoc ibcmp @@ -8,6 +8,8 @@ #define VERSION_MAX 0x7FFFFFFF /* +=for apidoc_section Versioning + =for apidoc prescan_version Validate that a given string can be parsed as a version object, but doesn't |