From fe64bd37d6f09b6de0307a65d28dc4539bcdc870 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Mon, 10 Jun 2024 15:06:05 -0600 Subject: [PATCH] perlapi: Combine all forms of pad_add_name() Having one group containing the descriptions of all closely related functions makes the pod more compact and makes maintenance easier; fixes only need to be applied in one place. And it encourages the documentation authors to compare and contrast the variants, paying closer attention to the subtle differences between them. And it is easier for the reader to choose the variant that is best for their current purpose, rather than hopping around the file, unsure if the current text is identical to that found elsewhere, or if there is a subtle nuance (or three). --- pad.c | 48 ++++++++++++++++++++++-------------------------- 1 file changed, 22 insertions(+), 26 deletions(-) diff --git a/pad.c b/pad.c index b61ee3e80b8b..ee9af633092c 100644 --- a/pad.c +++ b/pad.c @@ -53,7 +53,7 @@ AV which is C<@_>. Other entries are storage for variables and op targets. Iterating over the PADNAMELIST iterates over all possible pad items. Pad slots for targets (C) -and GVs end up having &PL_padname_undef "names", while slots for constants +and GVs end up having &PL_padname_undef "names", while slots for constants have C<&PL_padname_const> "names" (see C>). That C<&PL_padname_undef> and C<&PL_padname_const> are used is an implementation detail subject to @@ -581,15 +581,17 @@ S_pad_alloc_name(pTHX_ PADNAME *name, U32 flags, HV *typestash, } /* -=for apidoc pad_add_name_pvn +=for apidoc pad_add_name_pv +=for apidoc_item pad_add_name_pvn +=for apidoc_item pad_add_name_sv -Allocates a place in the currently-compiling pad for a named lexical -variable. Stores the name and other metadata in the name part of the -pad, and makes preparations to manage the variable's lexical scoping. -Returns the offset of the allocated pad slot. +These each allocate a place in the currently-compiling pad for a named lexical +variable. They store the name and other metadata in the name part of the +pad, and make preparations to manage the variable's lexical scoping. +They return the offset of the allocated pad slot. + +They differ only in how the input variable's name is specified. -C/C specify the variable's name in UTF-8, including -leading sigil. If C is non-null, the name is for a typed lexical, and this identifies the type. If C is non-null, it's a lexical reference to a package variable, and this identifies the package. The following @@ -600,6 +602,18 @@ flags can be OR'ed together: padadd_NO_DUP_CHECK skip check for lexical shadowing padadd_FIELD specifies that the lexical is a field for a class +In all forms, the variable name must include the leading sigil. + +In C, the input name is taken from the SV parameter using +C()>. + +In C, the input name is a NUL-terminated string, which must be +encoded in UTF-8. + +In C, C gives the length of the input name in bytes, +which means it may contain embedded NUL characters. Again, it must be encoded +in UTF-8. + =cut */ @@ -654,15 +668,6 @@ Perl_pad_add_name_pvn(pTHX_ const char *namepv, STRLEN namelen, return offset; } -/* -=for apidoc pad_add_name_pv - -Exactly like L, but takes a nul-terminated string -instead of a string/length pair. - -=cut -*/ - PADOFFSET Perl_pad_add_name_pv(pTHX_ const char *name, const U32 flags, HV *typestash, HV *ourstash) @@ -671,15 +676,6 @@ Perl_pad_add_name_pv(pTHX_ const char *name, return pad_add_name_pvn(name, strlen(name), flags, typestash, ourstash); } -/* -=for apidoc pad_add_name_sv - -Exactly like L, but takes the name string in the form -of an SV instead of a string/length pair. - -=cut -*/ - PADOFFSET Perl_pad_add_name_sv(pTHX_ SV *name, U32 flags, HV *typestash, HV *ourstash) {