diff options
| -rw-r--r-- | XSUB.h | 6 | ||||
| -rw-r--r-- | autodoc.pl | 27 | ||||
| -rw-r--r-- | cop.h | 6 | ||||
| -rw-r--r-- | handy.h | 46 | ||||
| -rw-r--r-- | hv.c | 4 | ||||
| -rw-r--r-- | inline.h | 14 | ||||
| -rw-r--r-- | mathoms.c | 12 | ||||
| -rw-r--r-- | mg.c | 8 | ||||
| -rw-r--r-- | op.c | 18 | ||||
| -rw-r--r-- | op.h | 10 | ||||
| -rw-r--r-- | pad.c | 4 | ||||
| -rw-r--r-- | perl.c | 14 | ||||
| -rw-r--r-- | perl.h | 48 | ||||
| -rw-r--r-- | pod/perlguts.pod | 20 | ||||
| -rw-r--r-- | pp.h | 2 | ||||
| -rw-r--r-- | pp_ctl.c | 2 | ||||
| -rw-r--r-- | pp_sys.c | 2 | ||||
| -rw-r--r-- | regen/unicode_constants.pl | 2 | ||||
| -rw-r--r-- | regexec.c | 2 | ||||
| -rw-r--r-- | scope.c | 2 | ||||
| -rw-r--r-- | scope.h | 2 | ||||
| -rw-r--r-- | sv.c | 10 | ||||
| -rw-r--r-- | sv.h | 8 | ||||
| -rw-r--r-- | unicode_constants.h | 2 | ||||
| -rw-r--r-- | universal.c | 2 | ||||
| -rw-r--r-- | util.c | 18 | ||||
| -rw-r--r-- | util.h | 2 |
27 files changed, 152 insertions, 141 deletions
@@ -14,7 +14,7 @@ /* first, some documentation for xsubpp-generated items */ /* -=for apidoc_section XS +=for apidoc_section $XS F<xsubpp> compiles XS code into C. See L<perlutil/xsubpp>. @@ -215,7 +215,7 @@ is a lexical C<$_> in scope. /* Typically used to return values from XS functions. */ /* -=for apidoc_section Stack Manipulation Macros +=for apidoc_section $stack =for apidoc Am|void|XST_mIV|int pos|IV iv Place an integer into the specified position C<pos> on the stack. The @@ -291,7 +291,7 @@ C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">. Macro to verify that the perl api version an XS module has been compiled against matches the api version of the perl interpreter it's being loaded into. -=for apidoc_section Exception Handling (simple) Macros +=for apidoc_section $exceptions =for apidoc Amns||dXCPT Set up necessary local variables for exception handling. diff --git a/autodoc.pl b/autodoc.pl index 0e13945483..31f98bd9af 100644 --- a/autodoc.pl +++ b/autodoc.pl @@ -24,15 +24,21 @@ use Text::Tabs; # Throughout the files read by this script are lines like # # =for apidoc_section Section Name +# =for apidoc_section $section_name_variable # # "Section Name" (after having been stripped of leading space) must be one of -# the legal section names, or an error is thrown. All API elements defined -# between this line and the next 'apidoc_section' line will go into the -# section "Section Name", sorted by dictionary order within it. perlintern -# and perlapi are parallel documents, each potentially with a section "Section -# Name". Each element is marked as to which document it goes into. If there -# are none for a particular section in perlapi, that section is -# omitted. +# the legal section names, or an error is thrown. $section_name_variable must +# be one of the legal section name variables defined below; these expand to +# legal section names. This form is used so that minor wording changes in +# these titles can be confied to this file. All the names of the variables +# end in '_scn'; this suffix is optional in the apidoc_section lines. +# +# All API elements defined between this line and the next 'apidoc_section' +# line will go into the section "Section Name" (or $section_name_variable), +# sorted by dictionary order within it. perlintern and perlapi are parallel +# documents, each potentially with a section "Section Name". Each element is +# marked as to which document it goes into. If there are none for a +# particular section in perlapi, that section is omitted. # # Also, in .[ch] files, there may be # @@ -44,7 +50,7 @@ use Text::Tabs; # are used as a heading for section "Section Name" (in both perlintern and # perlapi). This includes any =head[2-5]. If more than one '=head1 Section # Name' line has content, they appear in the generated pod in an undefined -# order. +# order. Note that you can't use a $section_name_variable in =head1 lines # # The next =head1, =for apidoc_section, or file end terminates what goes into # the current section @@ -407,6 +413,11 @@ sub autodoc ($$) { # parse a file and extract documentation info if ($in=~ /^ = (?: for [ ]+ apidoc_section | head1 ) [ ]+ (.*) /x) { $section = $1; + if ($section =~ / ^ \$ /x) { + $section .= '_scn' unless $section =~ / _scn $ /; + $section = eval "$section"; + die "Unknown \$section variable '$section' in $file: $@" if $@; + } die "Unknown section name '$section' in $file near line $.\n" unless defined $valid_sections{$section}; @@ -166,7 +166,7 @@ typedef struct jmpenv JMPENV; } STMT_END /* -=for apidoc_section COP Hint Hashes +=for apidoc_section $COP */ typedef struct refcounted_he COPHH; @@ -1083,7 +1083,7 @@ typedef struct stackinfo PERL_SI; } STMT_END /* -=for apidoc_section Utility Functions +=for apidoc_section $utility =for apidoc Amn|bool|IN_PERL_COMPILETIME Returns 1 if this macro is being called during the compilation phase of the program; otherwise 0; @@ -1098,7 +1098,7 @@ program; otherwise 0; #define IN_PERL_RUNTIME cBOOL(PL_curcop != &PL_compiling) /* -=for apidoc_section Multicall Functions +=for apidoc_section $multicall =for apidoc Amns||dMULTICALL Declare local variables for a multicall. See L<perlcall/LIGHTWEIGHT CALLBACKS>. @@ -18,12 +18,12 @@ # define Null(type) ((type)NULL) /* -=for apidoc_section String Handling +=for apidoc_section $string =for apidoc AmnU||Nullch Null character pointer. (No longer available when C<PERL_CORE> is defined.) -=for apidoc_section SV Handling +=for apidoc_section $SV =for apidoc AmnU||Nullsv Null SV pointer. (No longer available when C<PERL_CORE> is defined.) @@ -32,21 +32,21 @@ Null SV pointer. (No longer available when C<PERL_CORE> is defined.) 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_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_section $filesystem =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|FILE *f -=for apidoc_section String Handling +=for apidoc_section $string =for apidoc Amu|token|CAT2|token x|token y =for apidoc Amu|string|STRINGIFY|token x -=for apidoc_section Numeric Functions +=for apidoc_section $numeric =for apidoc Am|double|Drand01 =for apidoc Am|void|seedDrand01|Rand_seed_t x =for apidoc Am|char *|Gconvert|double x|Size_t n|bool t|char * b @@ -69,7 +69,7 @@ from it, and are very unlikely to change #define FALSE (0) /* -=for apidoc_section SV Handling +=for apidoc_section $SV =for apidoc Am|void *|MUTABLE_PTR|void * p =for apidoc_item |AV *|MUTABLE_AV|AV * p =for apidoc_item |CV *|MUTABLE_CV|CV * p @@ -138,7 +138,7 @@ already-built-in ones return pointers to what their names indicate. #endif /* -=for apidoc_section Casting +=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: @@ -320,7 +320,7 @@ typedef U64TYPE U64; #define nBIT_UMAX(n) nBIT_MASK(n) /* -=for apidoc_section Compiler directives +=for apidoc_section $directives =for apidoc Am||__ASSERT_|bool expr This is a helper macro to avoid preprocessor issues, replaced by nothing @@ -342,7 +342,7 @@ detects that and gets all excited. */ #endif /* -=for apidoc_section SV Handling +=for apidoc_section $SV =for apidoc Ama|SV*|newSVpvs|"literal string" Like C<newSVpvn>, but takes a literal string instead of a @@ -384,7 +384,7 @@ string/length pair. Like C<sv_setref_pvn>, but takes a literal string instead of a string/length pair. -=for apidoc_section String Handling +=for apidoc_section $string =for apidoc Ama|char*|savepvs|"literal string" Like C<savepvn>, but takes a literal string instead of a @@ -394,13 +394,13 @@ string/length pair. A version of C<savepvs()> which allocates the duplicate string in memory which is shared between threads. -=for apidoc_section GV Handling +=for apidoc_section $GV =for apidoc Am|HV*|gv_stashpvs|"name"|I32 create Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair. -=for apidoc_section HV Handling +=for apidoc_section $HV =for apidoc Am|SV**|hv_fetchs|HV* tb|"key"|I32 lval Like C<hv_fetch>, but takes a literal string instead of a @@ -411,7 +411,7 @@ Like C<hv_store>, but takes a literal string instead of a string/length pair and omits the hash parameter. -=for apidoc_section Lexer interface +=for apidoc_section $lexer =for apidoc Amx|void|lex_stuff_pvs|"pv"|U32 flags @@ -422,7 +422,7 @@ a string/length pair. */ /* -=for apidoc_section String Handling +=for apidoc_section $string =for apidoc Amu|pair|STR_WITH_LEN|"literal string" @@ -497,7 +497,7 @@ Perl_xxx(aTHX_ ...) form for any API calls where it's used. PERL_VERSION_PATCH) /* -=for apidoc_section Versioning +=for apidoc_section $versioning =for apidoc AmR|bool|PERL_VERSION_EQ|const U8 major|const U8 minor|const U8 patch =for apidoc_item PERL_VERSION_NE =for apidoc_item PERL_VERSION_LT @@ -567,7 +567,7 @@ becomes # define PERL_VERSION_GT(j,n,p) (! PERL_VERSION_LE(j,n,p)) /* -=for apidoc_section String Handling +=for apidoc_section $string =for apidoc Am|bool|strNE|char* s1|char* s2 Test two C<NUL>-terminated strings to see if they are different. Returns true @@ -1135,7 +1135,7 @@ difference is that this returns true only if the input character also matches L</isWORDCHAR>. See the L<top of this section|/Character classification> for an explanation of the variants. -=for apidoc_section Numeric Functions +=for apidoc_section $numeric =for apidoc Am|U8|READ_XDIGIT|char str* Returns the value of an ASCII-range hex digit and advances the string pointer. @@ -1336,7 +1336,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_section $integer =for apidoc AyT||WIDEST_UTYPE Yields the widest unsigned integer type on the platform, currently either @@ -2441,7 +2441,7 @@ typedef U32 line_t; #define isALPHA_FOLD_NE(c1, c2) (! isALPHA_FOLD_EQ((c1), (c2))) /* -=for apidoc_section Memory Management +=for apidoc_section $memory =for apidoc Am|void|Newx|void* ptr|int nitems|type The XSUB-writer's interface to the C C<malloc> function. @@ -2482,7 +2482,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_section $string =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 @@ -2515,7 +2515,7 @@ Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call optimise. -=for apidoc_section Utility Functions +=for apidoc_section $utility =for apidoc Amu|void|StructCopy|type *src|type *dest|type This is an architecture-independent macro to copy one structure to another. @@ -2730,7 +2730,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))) /* -=for apidoc_section Utility Functions +=for apidoc_section $utility =for apidoc Am|STRLEN|C_ARRAY_LENGTH|void *a @@ -3731,7 +3731,7 @@ Perl_refcounted_he_inc(pTHX_ struct refcounted_he *he) } /* -=for apidoc_section COP Hint Hashes +=for apidoc_section $COP =for apidoc cop_fetch_label Returns the label attached to a cop, and stores its length in bytes into @@ -3811,7 +3811,7 @@ Perl_cop_store_label(pTHX_ COP *const cop, const char *label, STRLEN len, } /* -=for apidoc_section HV Handling +=for apidoc_section $HV =for apidoc hv_assert Check that a hash is in an internally consistent state. @@ -40,7 +40,7 @@ SOFTWARE. /* ------------------------------- av.h ------------------------------- */ /* -=for apidoc_section AV Handling +=for apidoc_section $AV =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 @@ -60,7 +60,7 @@ Perl_av_count(pTHX_ AV *av) /* ------------------------------- cv.h ------------------------------- */ /* -=for apidoc_section CV Handling +=for apidoc_section $CV =for apidoc CvGV Returns the GV associated with the CV C<sv>, reifying it if necessary. @@ -311,7 +311,7 @@ S_sv_or_pv_pos_u2b(pTHX_ SV *sv, const char *pv, STRLEN pos, STRLEN *lenp) /* ------------------------------- utf8.h ------------------------------- */ /* -=for apidoc_section Unicode Support +=for apidoc_section $unicode */ PERL_STATIC_INLINE void @@ -1884,7 +1884,7 @@ Perl_utf8_to_uvchr_buf_helper(pTHX_ const U8 *s, const U8 *send, STRLEN *retlen) /* ------------------------------- perl.h ----------------------------- */ /* -=for apidoc_section Utility Functions +=for apidoc_section $utility =for apidoc is_safe_syscall @@ -2457,7 +2457,7 @@ Perl_cx_popgiven(pTHX_ PERL_CONTEXT *cx) /* ------------------ util.h ------------------------------------------- */ /* -=for apidoc_section String Handling +=for apidoc_section $string =for apidoc foldEQ @@ -2513,7 +2513,7 @@ Perl_foldEQ_latin1(const char *s1, const char *s2, I32 len) } /* -=for apidoc_section Locales +=for apidoc_section $locale =for apidoc foldEQ_locale Returns true if the leading C<len> bytes of the strings C<s1> and C<s2> are the @@ -2541,7 +2541,7 @@ Perl_foldEQ_locale(const char *s1, const char *s2, I32 len) } /* -=for apidoc_section String Handling +=for apidoc_section $string =for apidoc my_strnlen The C library C<strnlen> if available, or a Perl implementation of it. @@ -85,7 +85,7 @@ Perl_ref(pTHX_ OP *o, I32 type) } /* -=for apidoc_section SV Handling +=for apidoc_section $SV =for apidoc sv_unref Unsets the RV status of the SV, and decrements the reference count of @@ -606,7 +606,7 @@ Perl_gv_efullname3(pTHX_ SV *sv, const GV *gv, const char *prefix) } /* -=for apidoc_section GV Handling +=for apidoc_section $GV =for apidoc gv_fetchmethod See L</gv_fetchmethod_autoload>. @@ -704,7 +704,7 @@ Perl_is_utf8_string_loc(const U8 *s, const STRLEN len, const U8 **ep) } /* -=for apidoc_section SV Handling +=for apidoc_section $SV =for apidoc sv_nolocking Dummy routine which "locks" an SV when there is no locking module present. @@ -822,7 +822,7 @@ Perl_sv_usepvn(pTHX_ SV *sv, char *ptr, STRLEN len) } /* -=for apidoc_section Pack and Unpack +=for apidoc_section $pack =for apidoc unpack_str The engine implementing C<unpack()> Perl function. Note: parameters C<strbeg>, @@ -1119,7 +1119,7 @@ Perl_sv_2bool(pTHX_ SV *const sv) /* -=for apidoc_section Custom Operators +=for apidoc_section $custom =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 @@ -1182,7 +1182,7 @@ ASCII_TO_NEED(const UV enc, const UV ch) } /* -=for apidoc_section Unicode Support +=for apidoc_section $unicode =for apidoc is_utf8_char Tests if some arbitrary number of bytes begins in a valid UTF-8 @@ -842,7 +842,7 @@ S_fixup_errno_string(pTHX_ SV* sv) } /* -=for apidoc_section Errno +=for apidoc_section $errno =for apidoc sv_string_from_errnum Generates the message string describing an OS error and returns it as @@ -1906,7 +1906,7 @@ Perl_magic_setnkeys(pTHX_ SV *sv, MAGIC *mg) } /* -=for apidoc_section Magic +=for apidoc_section $magic =for apidoc magic_methcall Invoke a magic method (like FETCH). @@ -3353,7 +3353,7 @@ Perl_magic_set(pTHX_ SV *sv, MAGIC *mg) } /* -=for apidoc_section Signals +=for apidoc_section $signals =for apidoc whichsig =for apidoc_item whichsig_pv =for apidoc_item whichsig_pvn @@ -3713,7 +3713,7 @@ S_unwind_handler_stack(pTHX_ const void *p) } /* -=for apidoc_section Magic +=for apidoc_section $magic =for apidoc magic_sethint Triggered by a store to C<%^H>, records the key/value pair to @@ -789,7 +789,7 @@ Perl_allocmy(pTHX_ const char *const name, const STRLEN len, const U32 flags) } /* -=for apidoc_section Optree Manipulation Functions +=for apidoc_section $optree_manipulation =for apidoc alloccopstash @@ -5789,7 +5789,7 @@ Perl_block_end(pTHX_ I32 floor, OP *seq) } /* -=for apidoc_section Compile-time scope hooks +=for apidoc_section $scope =for apidoc blockhook_register @@ -6336,7 +6336,7 @@ S_gen_constant_list(pTHX_ OP *o) } /* -=for apidoc_section Optree Manipulation Functions +=for apidoc_section $optree_manipulation */ /* List constructors */ @@ -6508,7 +6508,7 @@ Perl_op_convert_list(pTHX_ I32 type, I32 flags, OP *o) /* -=for apidoc_section Optree construction +=for apidoc_section $optree_construction =for apidoc newNULLLIST @@ -8877,7 +8877,7 @@ Perl_utilize(pTHX_ int aver, I32 floor, OP *version, OP *idop, OP *arg) } /* -=for apidoc_section Embedding and Interpreter Cloning +=for apidoc_section $embedding =for apidoc load_module @@ -9025,7 +9025,7 @@ Perl_dofile(pTHX_ OP *term, I32 force_builtin) } /* -=for apidoc_section Optree construction +=for apidoc_section $optree_construction =for apidoc newSLICEOP @@ -10613,7 +10613,7 @@ static void const_av_xsub(pTHX_ CV* cv); /* -=for apidoc_section Optree Manipulation Functions +=for apidoc_section $optree_manipulation =for apidoc cv_const_sv @@ -17996,7 +17996,7 @@ Perl_peep(pTHX_ OP *o) } /* -=for apidoc_section Custom Operators +=for apidoc_section $custom =for apidoc Perl_custom_op_xop Return the XOP structure for a given custom op. This macro should be @@ -18398,7 +18398,7 @@ Perl_report_redefined_cv(pTHX_ const SV *name, const CV *old_cv, } /* -=for apidoc_section Hook manipulation +=for apidoc_section $hook These functions provide convenient and thread-safe means of manipulating hook variables. @@ -70,7 +70,7 @@ typedef PERL_BITFIELD16 Optype; #define OP_GIMME_REVERSE(flags) ((flags) & G_WANT) /* -=for apidoc_section Callback Functions +=for apidoc_section $callback =for apidoc Amn|U32|GIMME_V The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>, @@ -639,7 +639,7 @@ typedef struct { /* -=for apidoc_section Optree Manipulation Functions +=for apidoc_section $optree_manipulation =for apidoc Am|OP*|LINKLIST|OP *o Given the root of an optree, link the tree in execution order using the @@ -751,7 +751,7 @@ struct block_hooks { }; /* -=for apidoc_section Compile-time scope hooks +=for apidoc_section $scope =for apidoc mx|U32|BhkFLAGS|BHK *hk Return the BHK's flags. @@ -849,7 +849,7 @@ preprocessing token; the type of C<arg> depends on C<which>. #define OP_LVALUE_NO_CROAK 1 /* -=for apidoc_section Custom Operators +=for apidoc_section $custom =for apidoc Am|U32|XopFLAGS|XOP *xop Return the XOP's flags. @@ -945,7 +945,7 @@ typedef enum { (Perl_custom_op_get_field(x, XOPe_xop_ptr).xop_ptr) /* -=for apidoc_section Optree Manipulation Functions +=for apidoc_section $optree_manipulation =for apidoc Am|const char *|OP_NAME|OP *o Return the name of the provided OP. For core ops this looks up the name @@ -19,7 +19,7 @@ */ /* -=for apidoc_section Pad Data Structures +=for apidoc_section $pad =for apidoc Amx|PADLIST *|CvPADLIST|CV *cv @@ -272,7 +272,7 @@ Perl_pad_new(pTHX_ int flags) /* -=for apidoc_section Embedding and Interpreter Cloning +=for apidoc_section $embedding =for apidoc cv_undef @@ -177,7 +177,7 @@ perl_alloc_using(struct IPerlMem* ipM, struct IPerlMem* ipMS, #else /* -=for apidoc_section Embedding and Interpreter Cloning +=for apidoc_section $embedding =for apidoc perl_alloc @@ -2746,7 +2746,7 @@ S_run_body(pTHX_ I32 oldscope) } /* -=for apidoc_section SV Handling +=for apidoc_section $SV =for apidoc get_sv @@ -2772,7 +2772,7 @@ Perl_get_sv(pTHX_ const char *name, I32 flags) } /* -=for apidoc_section AV Handling +=for apidoc_section $AV =for apidoc get_av @@ -2802,7 +2802,7 @@ Perl_get_av(pTHX_ const char *name, I32 flags) } /* -=for apidoc_section HV Handling +=for apidoc_section $HV =for apidoc get_hv @@ -2829,7 +2829,7 @@ Perl_get_hv(pTHX_ const char *name, I32 flags) } /* -=for apidoc_section CV Handling +=for apidoc_section $CV =for apidoc get_cvn_flags @@ -2881,7 +2881,7 @@ Perl_get_cv(pTHX_ const char *name, I32 flags) /* -=for apidoc_section Callback Functions +=for apidoc_section $callback =for apidoc call_argv @@ -3275,7 +3275,7 @@ Perl_eval_pv(pTHX_ const char *p, I32 croak_on_error) /* Require a module. */ /* -=for apidoc_section Embedding and Interpreter Cloning +=for apidoc_section $embedding =for apidoc require_pv @@ -84,7 +84,7 @@ /* <--- here ends the logic shared by perl.h and makedef.pl */ /* -=for apidoc_section Compiler directives +=for apidoc_section $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 @@ -183,7 +183,7 @@ Otherwise ends a section of code already begun by a C<L</START_EXTERN_C>>. * * The only one Devel::PPPort handles is this; list it as deprecated -=for apidoc_section Concurrency +=for apidoc_section $concurrency =for apidoc AmD|void|CPERLscope|void x Now a no-op. @@ -406,7 +406,7 @@ Now a no-op. * cpp macros like PERL_UNUSED_DECL cannot work for this purpose, even * if it were PERL_UNUSED_DECL(x), which it cannot be (see above). -=for apidoc_section Compiler directives +=for apidoc_section $directives =for apidoc AmnU||PERL_UNUSED_DECL Tells the compiler that the parameter in the function prototype just before it is not necessarily expected to be used in the function. Not that many @@ -631,7 +631,7 @@ code. #endif /* -=for apidoc_section Concurrency +=for apidoc_section $concurrency =for apidoc AmnU||dVAR This is now a synonym for dNOOP: declare nothing @@ -679,7 +679,7 @@ This is now a synonym for dNOOP: declare nothing #endif /* -=for apidoc_section Compiler directives +=for apidoc_section $directives =for apidoc AmnUu|void|STMT_START =for apidoc_item ||STMT_END @@ -1068,7 +1068,7 @@ EXTERN_C int usleep(unsigned int); /* Macros for correct constant construction. These are in C99 <stdint.h> * (so they will not be available in strict C89 mode), but they are nice, so * let's define them if necessary. -=for apidoc_section Integer configuration values +=for apidoc_section $integer =for apidoc Am|I16|INT16_C|number =for apidoc_item |I32|INT32_C|number =for apidoc_item |I64|INT64_C|number @@ -1158,7 +1158,7 @@ Use C<L</UINTMAX_C>> to get the largest type available on the platform. # endif /* -=for apidoc_section Integer configuration values +=for apidoc_section $integer =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 @@ -1495,7 +1495,7 @@ EXTERN_C char *crypt(const char *, const char *); #endif /* -=for apidoc_section Errno +=for apidoc_section $errno =for apidoc m|void|SETERRNO|int errcode|int vmserrcode @@ -1598,7 +1598,7 @@ was saved by C<dSAVE_ERRNO> or C<RESTORE_ERRNO>. #endif /* -=for apidoc_section Warning and Dieing +=for apidoc_section $warning =for apidoc Amn|SV *|ERRSV @@ -1676,7 +1676,7 @@ any magic. #endif /* -=for apidoc_section SV Handling +=for apidoc_section $SV =for apidoc Amn|SV *|DEFSV Returns the SV associated with C<$_> @@ -1898,7 +1898,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. -=for apidoc_section String Handling +=for apidoc_section $string =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 @@ -2722,7 +2722,7 @@ extern long double Perl_my_frexpl(long double x, int *e); #endif /* -=for apidoc_section Integer configuration values +=for apidoc_section $integer =for apidoc AmnU||PERL_INT_MAX =for apidoc_item ||PERL_INT_MIN @@ -3142,7 +3142,7 @@ typedef struct padname PADNAME; #endif /* -=for apidoc_section Embedding and Interpreter Cloning +=for apidoc_section $embedding =for apidoc Am|void|PERL_SYS_INIT|int *argc|char*** argv Provides system-specific tune up of the C runtime environment necessary to @@ -3739,7 +3739,7 @@ EXTERN_C int perl_tsa_mutex_unlock(perl_mutex* mutex) #endif /* -=for apidoc_section Compiler directives +=for apidoc_section $directives =for apidoc Am||LIKELY|bool expr @@ -4190,7 +4190,7 @@ my_swap16(const U16 x) { out of range floating point values to integers *is* undefined behaviour, and it is starting to bite. -=for apidoc_section Casting +=for apidoc_section $casting =for apidoc Am|I32|I_32|NV what Cast an NV to I32 while avoiding undefined C behavior @@ -4230,7 +4230,7 @@ Cast an NV to UV while avoiding undefined C behavior #define U_L(what) U_32(what) /* -=for apidoc_section Integer configuration values +=for apidoc_section $integer =for apidoc Amn|IV|IV_MAX The largest signed integer that fits in an IV on this platform. @@ -4864,7 +4864,7 @@ EXTCONST char PL_Zero[] INIT("0"); /* -=for apidoc_section Numeric Functions +=for apidoc_section $numeric =for apidoc AmTuU|const char *|PL_hexdigit|U8 value This array, indexed by an integer, converts that value into the character that @@ -6342,7 +6342,7 @@ typedef struct am_table_short AMTS; cBOOL(PL_hints & (HINT_LOCALE|HINT_LOCALE_PARTIAL)) /* -=for apidoc_section Locales +=for apidoc_section $locale =for apidoc Amn|bool|IN_LOCALE @@ -6610,7 +6610,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.) -=for apidoc_section Locales +=for apidoc_section $locale =for apidoc Amn|void|DECLARATION_FOR_LC_NUMERIC_MANIPULATION @@ -6903,7 +6903,7 @@ cannot have changed since the precalculation. /* -=for apidoc_section Numeric Functions +=for apidoc_section $numeric =for apidoc AmTR|NV|Strtod|NN const char * const s|NULLOK char ** e @@ -7231,7 +7231,7 @@ EXTERN_C int flock(int fd, int op); #define IS_NUMBER_TRAILING 0x40 /* number has trailing trash */ /* -=for apidoc_section Numeric Functions +=for apidoc_section $numeric =for apidoc AmdR|bool|GROK_NUMERIC_RADIX|NN const char **sp|NN const char *send @@ -7344,7 +7344,7 @@ extern void moncontrol(int); #endif /* -=for apidoc_section Signals +=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 @@ -7355,7 +7355,7 @@ unsafe signals. See L<perlrun/PERL_SIGNALS> and L<perlipc/Deferred Signals #define PERL_SIGNALS_UNSAFE_FLAG 0x0001 /* -=for apidoc_section Numeric Functions +=for apidoc_section $numeric =for apidoc Am|int|PERL_ABS|int @@ -7387,7 +7387,7 @@ so no C<x++>. /* -=for apidoc_section Utility Functions +=for apidoc_section $utility =for apidoc Am|bool|IS_SAFE_SYSCALL|NN const char *pv|STRLEN len|NN const char *what|NN const char *op_name diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 11e5e53990..06cc207496 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -21,11 +21,11 @@ Perl has three typedefs that handle Perl's three main data types: Each typedef has specific routines that manipulate the various data types. -=for apidoc_section AV Handling +=for apidoc_section $AV =for apidoc Ayh||AV -=for apidoc_section HV Handling +=for apidoc_section $HV =for apidoc Ayh||HV -=for apidoc_section SV Handling +=for apidoc_section $SV =for apidoc Ayh||SV =head2 What is an "IV"? @@ -55,7 +55,7 @@ may not be usable in all circumstances. A numeric constant can be specified with L<perlapi/C<INT16_C>>, L<perlapi/C<UINTMAX_C>>, and similar. -=for apidoc_section Integer configuration values +=for apidoc_section $integer =for apidoc Ayh||I8 =for apidoc_item ||I16 =for apidoc_item ||I32 @@ -590,7 +590,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_section $HV =for apidoc Amh|void|PERL_HASH|U32 hash|char *key|STRLEN klen =head2 Hash API Extensions @@ -1629,7 +1629,7 @@ Inside such a I<pseudo-block> the following service is available: These macros arrange things to restore the value of integer variable C<i> at the end of the enclosing I<pseudo-block>. -=for apidoc_section Stack Manipulation Macros +=for apidoc_section $stack =for apidoc Amh||SAVEINT|int i =for apidoc Amh||SAVEIV|IV i =for apidoc Amh||SAVEI32|I32 i @@ -2493,7 +2493,7 @@ function used within the Perl guts: STATIC becomes "static" in C, and may be #define'd to nothing in some configurations in the future. -=for apidoc_section Compiler directives +=for apidoc_section $directives =for apidoc Ayh||STATIC A public function (i.e. part of the internal API, but not necessarily @@ -2509,7 +2509,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_section $concurrency =for apidoc Amnh||aTHX =for apidoc Amnh||aTHX_ =for apidoc Amnh||dTHX @@ -2844,7 +2844,7 @@ 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 +=for apidoc_section $formats =for apidoc Amnh||UTF8f =for apidoc Amh||UTF8fARG|bool is_utf8|Size_t byte_len|char *str @@ -2879,7 +2879,7 @@ use the follow macros to do it right. PTR2NV(pointer) INT2PTR(pointertotype, integer) -=for apidoc_section Casting +=for apidoc_section $casting =for apidoc Amh|type|INT2PTR|type|int value =for apidoc Amh|UV|PTR2UV|void * ptr =for apidoc Amh|IV|PTR2IV|void * ptr @@ -11,7 +11,7 @@ #define PP(s) OP * Perl_##s(pTHX) /* -=for apidoc_section Stack Manipulation Macros +=for apidoc_section $stack =for apidoc AmnU||SP Stack pointer. This is usually handled by C<xsubpp>. See C<L</dSP>> and @@ -1846,7 +1846,7 @@ PP(pp_xor) /* -=for apidoc_section CV Handling +=for apidoc_section $CV =for apidoc caller_cx @@ -1293,7 +1293,7 @@ PP(pp_sselect) /* -=for apidoc_section GV Handling +=for apidoc_section $GV =for apidoc setdefout diff --git a/regen/unicode_constants.pl b/regen/unicode_constants.pl index 7851e87e22..aba447ae6a 100644 --- a/regen/unicode_constants.pl +++ b/regen/unicode_constants.pl @@ -29,7 +29,7 @@ print $out_fh <<END; * with no additional suffix are both string constants */ /* -=for apidoc_section Unicode Support +=for apidoc_section \$unicode =for apidoc AmnU|const char *|BOM_UTF8 @@ -10913,7 +10913,7 @@ Perl_is_grapheme(pTHX_ const U8 * strbeg, const U8 * s, const U8 * strend, const } /* -=for apidoc_section Unicode Support +=for apidoc_section $unicode =for apidoc isSCRIPT_RUN @@ -316,7 +316,7 @@ Perl_save_set_svflags(pTHX_ SV* sv, U32 mask, U32 val) /* -=for apidoc_section GV Handling +=for apidoc_section $GV =for apidoc save_gp @@ -152,7 +152,7 @@ /* -=for apidoc_section Callback Functions +=for apidoc_section $callback =for apidoc Amns||SAVETMPS Opening bracket for temporaries on a callback. See C<L</FREETMPS>> and @@ -130,7 +130,7 @@ static const char S_destroy[] = "DESTROY"; /* ============================================================================ -=for apidoc_section SV Handling +=for apidoc_section $SV 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 @@ -408,7 +408,7 @@ S_del_sv(pTHX_ SV *p) /* -=for apidoc_section SV Handling +=for apidoc_section $SV =for apidoc sv_add_arena @@ -13454,7 +13454,7 @@ Perl_sv_vcatpvfn_flags(pTHX_ SV *const sv, const char *const pat, const STRLEN p /* ========================================================================= -=for apidoc_section Embedding and Interpreter Cloning +=for apidoc_section $embedding =cut @@ -16042,7 +16042,7 @@ Perl_init_constants(pTHX) } /* -=for apidoc_section Unicode Support +=for apidoc_section $unicode =for apidoc sv_recode_to_utf8 @@ -16313,7 +16313,7 @@ Perl_varname(pTHX_ const GV *const gv, const char gvtype, PADOFFSET targ, /* -=apidoc_section Warning and Dieing +=apidoc_section $warning =for apidoc find_uninit_var Find the name of the undefined variable (if any) that caused the operator @@ -13,7 +13,7 @@ #endif /* -=for apidoc_section SV Flags +=for apidoc_section $SV_flags =for apidoc Ay||svtype An enum of flags for Perl types. These are found in the file F<sv.h> @@ -269,7 +269,7 @@ struct p5rx { #undef _SV_HEAD_UNION /* ensure no pollution */ /* -=for apidoc_section SV Handling +=for apidoc_section $SV =for apidoc Am|U32|SvREFCNT|SV* sv Returns the value of the object's reference count. Exposed @@ -2103,7 +2103,7 @@ incremented. /* the following macros update any magic values this C<sv> is associated with */ /* -=head1 Magic +=for apidoc_section $magic =for apidoc Am|void|SvGETMAGIC|SV* sv Invokes C<L</mg_get>> on an SV if it has 'get' magic. For example, this @@ -2142,7 +2142,7 @@ has been loaded. Releases a mutual exclusion lock on C<sv> if a suitable module has been loaded. -=for apidoc_section SV Handling +=for apidoc_section $SV =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/unicode_constants.h b/unicode_constants.h index 332307e853..232f18c464 100644 --- a/unicode_constants.h +++ b/unicode_constants.h @@ -22,7 +22,7 @@ * with no additional suffix are both string constants */ /* -=for apidoc_section Unicode Support +=for apidoc_section $unicode =for apidoc AmnU|const char *|BOM_UTF8 diff --git a/universal.c b/universal.c index 0cc6363b0a..9c49cd8327 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 } /* -=for apidoc_section SV Handling +=for apidoc_section $SV =for apidoc sv_derived_from_pvn @@ -542,7 +542,7 @@ Free_t Perl_mfree (Malloc_t where) #define DELIMCPY_OUT_OF_BOUNDS_RET I32_MAX /* -=for apidoc_section String Handling +=for apidoc_section $string =for apidoc delimcpy_no_escape Copy a source buffer to a destination buffer, stopping at (but not including) @@ -1301,7 +1301,7 @@ Perl_cntrl_to_mnemonic(const U8 c) /* copy a string to a safe spot */ /* -=for apidoc_section String Handling +=for apidoc_section $string =for apidoc savepv Perl's version of C<strdup()>. Returns a pointer to a newly allocated @@ -1796,7 +1796,7 @@ Perl_write_to_stderr(pTHX_ SV* msv) } /* -=for apidoc_section Warning and Dieing +=for apidoc_section $warning */ /* Common code used in dieing and warning */ @@ -2448,7 +2448,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_section $utility =for apidoc my_setenv A wrapper for the C library L<setenv(3)>. Don't use the latter, as the perl @@ -3035,7 +3035,7 @@ dup2(int oldfd, int newfd) #ifdef HAS_SIGACTION /* -=for apidoc_section Signals +=for apidoc_section $signals =for apidoc rsignal A wrapper for the C library L<signal(2)>. Don't use the latter, as the Perl @@ -3946,7 +3946,7 @@ Perl_init_tm(pTHX_ struct tm *ptm) /* see mktime, strftime and asctime */ } /* -=for apidoc_section Time +=for apidoc_section $time =for apidoc mini_mktime normalise S<C<struct tm>> values without the localtime() semantics (and overhead) of mktime(). @@ -4146,7 +4146,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_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 @@ -4255,7 +4255,7 @@ mini_mktime() overwrites them (dp->d_name[1] == '.' && dp->d_name[2] == '\0'))) /* -=for apidoc_section Utility Functions +=for apidoc_section $utility =for apidoc getcwd_sv @@ -5163,7 +5163,7 @@ Perl_mem_log_del_sv(const SV *sv, #endif /* PERL_MEM_LOG */ /* -=for apidoc_section String Handling +=for apidoc_section $string =for apidoc quadmath_format_valid C<quadmath_snprintf()> is very strict about its C<format> string and will @@ -37,7 +37,7 @@ #endif /* -=for apidoc_section String Handling +=for apidoc_section $string =for apidoc ibcmp |