In perl.git, the branch blead has been updated <https://perl5.git.perl.org/perl.git/commitdiff/1568d13a11564a7d9d62aaf6a79b9b04172a2a45?hp=bc3331071e1ccbdab715397718bb00282f5c5e88>
- Log ----------------------------------------------------------------- commit 1568d13a11564a7d9d62aaf6a79b9b04172a2a45 Author: Zefram <[email protected]> Date: Sun Nov 12 05:58:36 2017 +0000 better document macros taking literal strings When giving a function-style prototype for a macro taking a literal string parameter, put a string literal in place of a type for that parameter. This goofy appearance makes it obvious that this isn't really a function, and clues the reader in that the parameter can't actually be an arbitrary expression of the right type. Also change the nonsensical "NUL-terminated literal string" to "literal string" to describe these parameters. Fixes [perl #116286]. ----------------------------------------------------------------------- Summary of changes: cop.h | 16 ++++++++-------- handy.h | 62 +++++++++++++++++++++++++++++++------------------------------- hv.h | 8 ++++---- pad.h | 8 ++++---- scope.h | 2 +- 5 files changed, 48 insertions(+), 48 deletions(-) diff --git a/cop.h b/cop.h index 34ebbc09ab..5c66752859 100644 --- a/cop.h +++ b/cop.h @@ -190,9 +190,9 @@ associated with the key. Perl_refcounted_he_fetch_pvn(aTHX_ cophh, keypv, keylen, hash, flags) /* -=for apidoc Amx|SV *|cophh_fetch_pvs|const COPHH *cophh|const char *key|U32 flags +=for apidoc Amx|SV *|cophh_fetch_pvs|const COPHH *cophh|"literal string" key|U32 flags -Like L</cophh_fetch_pvn>, but takes a C<NUL>-terminated literal string instead +Like L</cophh_fetch_pvn>, but takes a literal string instead of a string/length pair, and no precomputed hash. =cut @@ -296,9 +296,9 @@ be stored with referential integrity, but will be coerced to strings. Perl_refcounted_he_new_pvn(aTHX_ cophh, keypv, keylen, hash, value, flags) /* -=for apidoc Amx|COPHH *|cophh_store_pvs|const COPHH *cophh|const char *key|SV *value|U32 flags +=for apidoc Amx|COPHH *|cophh_store_pvs|const COPHH *cophh|"literal string" key|SV *value|U32 flags -Like L</cophh_store_pvn>, but takes a C<NUL>-terminated literal string instead +Like L</cophh_store_pvn>, but takes a literal string instead of a string/length pair, and no precomputed hash. =cut @@ -353,9 +353,9 @@ hash of the key string, or zero if it has not been precomputed. (SV *)NULL, flags) /* -=for apidoc Amx|COPHH *|cophh_delete_pvs|const COPHH *cophh|const char *key|U32 flags +=for apidoc Amx|COPHH *|cophh_delete_pvs|const COPHH *cophh|"literal string" key|U32 flags -Like L</cophh_delete_pvn>, but takes a C<NUL>-terminated literal string instead +Like L</cophh_delete_pvn>, but takes a literal string instead of a string/length pair, and no precomputed hash. =cut @@ -493,9 +493,9 @@ associated with the key. cophh_fetch_pvn(CopHINTHASH_get(cop), keypv, keylen, hash, flags) /* -=for apidoc Am|SV *|cop_hints_fetch_pvs|const COP *cop|const char *key|U32 flags +=for apidoc Am|SV *|cop_hints_fetch_pvs|const COP *cop|"literal string" key|U32 flags -Like L</cop_hints_fetch_pvn>, but takes a C<NUL>-terminated literal string +Like L</cop_hints_fetch_pvn>, but takes a literal string instead of a string/length pair, and no precomputed hash. =cut diff --git a/handy.h b/handy.h index 77415ecb45..87c45471d1 100644 --- a/handy.h +++ b/handy.h @@ -296,78 +296,78 @@ typedef U64TYPE U64; /* =head1 SV-Body Allocation -=for apidoc Ama|SV*|newSVpvs|const char* s -Like C<newSVpvn>, but takes a C<NUL>-terminated literal string instead of a +=for apidoc Ama|SV*|newSVpvs|"literal string" s +Like C<newSVpvn>, but takes a literal string instead of a string/length pair. -=for apidoc Ama|SV*|newSVpvs_flags|const char* s|U32 flags -Like C<newSVpvn_flags>, but takes a C<NUL>-terminated literal string instead of +=for apidoc Ama|SV*|newSVpvs_flags|"literal string" s|U32 flags +Like C<newSVpvn_flags>, but takes a literal string instead of a string/length pair. -=for apidoc Ama|SV*|newSVpvs_share|const char* s -Like C<newSVpvn_share>, but takes a C<NUL>-terminated literal string instead of +=for apidoc Ama|SV*|newSVpvs_share|"literal string" s +Like C<newSVpvn_share>, but takes a literal string instead of a string/length pair and omits the hash parameter. -=for apidoc Am|void|sv_catpvs_flags|SV* sv|const char* s|I32 flags -Like C<sv_catpvn_flags>, but takes a C<NUL>-terminated literal string instead +=for apidoc Am|void|sv_catpvs_flags|SV* sv|"literal string" s|I32 flags +Like C<sv_catpvn_flags>, but takes a literal string instead of a string/length pair. -=for apidoc Am|void|sv_catpvs_nomg|SV* sv|const char* s -Like C<sv_catpvn_nomg>, but takes a C<NUL>-terminated literal string instead of +=for apidoc Am|void|sv_catpvs_nomg|SV* sv|"literal string" s +Like C<sv_catpvn_nomg>, but takes a literal string instead of a string/length pair. -=for apidoc Am|void|sv_catpvs|SV* sv|const char* s -Like C<sv_catpvn>, but takes a C<NUL>-terminated literal string instead of a +=for apidoc Am|void|sv_catpvs|SV* sv|"literal string" s +Like C<sv_catpvn>, but takes a literal string instead of a string/length pair. -=for apidoc Am|void|sv_catpvs_mg|SV* sv|const char* s -Like C<sv_catpvn_mg>, but takes a C<NUL>-terminated literal string instead of a +=for apidoc Am|void|sv_catpvs_mg|SV* sv|"literal string" s +Like C<sv_catpvn_mg>, but takes a literal string instead of a string/length pair. -=for apidoc Am|void|sv_setpvs|SV* sv|const char* s -Like C<sv_setpvn>, but takes a C<NUL>-terminated literal string instead of a +=for apidoc Am|void|sv_setpvs|SV* sv|"literal string" s +Like C<sv_setpvn>, but takes a literal string instead of a string/length pair. -=for apidoc Am|void|sv_setpvs_mg|SV* sv|const char* s -Like C<sv_setpvn_mg>, but takes a C<NUL>-terminated literal string instead of a +=for apidoc Am|void|sv_setpvs_mg|SV* sv|"literal string" s +Like C<sv_setpvn_mg>, but takes a literal string instead of a string/length pair. -=for apidoc Am|SV *|sv_setref_pvs|const char* s -Like C<sv_setref_pvn>, but takes a C<NUL>-terminated literal string instead of +=for apidoc Am|SV *|sv_setref_pvs|"literal string" s +Like C<sv_setref_pvn>, but takes a literal string instead of a string/length pair. =head1 Memory Management -=for apidoc Ama|char*|savepvs|const char* s -Like C<savepvn>, but takes a C<NUL>-terminated literal string instead of a +=for apidoc Ama|char*|savepvs|"literal string" s +Like C<savepvn>, but takes a literal string instead of a string/length pair. -=for apidoc Ama|char*|savesharedpvs|const char* s +=for apidoc Ama|char*|savesharedpvs|"literal string" s A version of C<savepvs()> which allocates the duplicate string in memory which is shared between threads. =head1 GV Functions -=for apidoc Am|HV*|gv_stashpvs|const char* name|I32 create -Like C<gv_stashpvn>, but takes a C<NUL>-terminated literal string instead of a +=for apidoc Am|HV*|gv_stashpvs|"literal string" name|I32 create +Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair. =head1 Hash Manipulation Functions -=for apidoc Am|SV**|hv_fetchs|HV* tb|const char* key|I32 lval -Like C<hv_fetch>, but takes a C<NUL>-terminated literal string instead of a +=for apidoc Am|SV**|hv_fetchs|HV* tb|"literal string" key|I32 lval +Like C<hv_fetch>, but takes a literal string instead of a string/length pair. -=for apidoc Am|SV**|hv_stores|HV* tb|const char* key|NULLOK SV* val -Like C<hv_store>, but takes a C<NUL>-terminated literal string instead of a +=for apidoc Am|SV**|hv_stores|HV* tb|"literal string" key|NULLOK SV* val +Like C<hv_store>, but takes a literal string instead of a string/length pair and omits the hash parameter. =head1 Lexer interface -=for apidoc Amx|void|lex_stuff_pvs|const char *pv|U32 flags +=for apidoc Amx|void|lex_stuff_pvs|"literal string" pv|U32 flags -Like L</lex_stuff_pvn>, but takes a C<NUL>-terminated literal string instead of +Like L</lex_stuff_pvn>, but takes a literal string instead of a string/length pair. =cut diff --git a/hv.h b/hv.h index 8411b5d31f..dcc6eb1e2f 100644 --- a/hv.h +++ b/hv.h @@ -565,9 +565,9 @@ struct refcounted_he { }; /* -=for apidoc m|SV *|refcounted_he_fetch_pvs|const struct refcounted_he *chain|const char *key|U32 flags +=for apidoc m|SV *|refcounted_he_fetch_pvs|const struct refcounted_he *chain|"literal string" key|U32 flags -Like L</refcounted_he_fetch_pvn>, but takes a C<NUL>-terminated literal string +Like L</refcounted_he_fetch_pvn>, but takes a literal string instead of a string/length pair, and no precomputed hash. =cut @@ -577,9 +577,9 @@ instead of a string/length pair, and no precomputed hash. Perl_refcounted_he_fetch_pvn(aTHX_ chain, STR_WITH_LEN(key), 0, flags) /* -=for apidoc m|struct refcounted_he *|refcounted_he_new_pvs|struct refcounted_he *parent|const char *key|SV *value|U32 flags +=for apidoc m|struct refcounted_he *|refcounted_he_new_pvs|struct refcounted_he *parent|"literal string" key|SV *value|U32 flags -Like L</refcounted_he_new_pvn>, but takes a C<NUL>-terminated literal string +Like L</refcounted_he_new_pvn>, but takes a literal string instead of a string/length pair, and no precomputed hash. =cut diff --git a/pad.h b/pad.h index 56d88abc8d..976dc058d4 100644 --- a/pad.h +++ b/pad.h @@ -492,9 +492,9 @@ Clone the state variables associated with running and compiling pads. PL_cop_seqmax = proto_perl->Icop_seqmax; /* -=for apidoc Am|PADOFFSET|pad_add_name_pvs|const char *name|U32 flags|HV *typestash|HV *ourstash +=for apidoc Am|PADOFFSET|pad_add_name_pvs|"literal string" name|U32 flags|HV *typestash|HV *ourstash -Exactly like L</pad_add_name_pvn>, but takes a C<NUL>-terminated literal string +Exactly like L</pad_add_name_pvn>, but takes a literal string instead of a string/length pair. =cut @@ -504,9 +504,9 @@ instead of a string/length pair. Perl_pad_add_name_pvn(aTHX_ STR_WITH_LEN(name), flags, typestash, ourstash) /* -=for apidoc Am|PADOFFSET|pad_findmy_pvs|const char *name|U32 flags +=for apidoc Am|PADOFFSET|pad_findmy_pvs|"literal string" name|U32 flags -Exactly like L</pad_findmy_pvn>, but takes a C<NUL>-terminated literal string +Exactly like L</pad_findmy_pvn>, but takes a literal string instead of a string/length pair. =cut diff --git a/scope.h b/scope.h index 88c182dc03..c6f4bc4350 100644 --- a/scope.h +++ b/scope.h @@ -175,7 +175,7 @@ given literal string with the new scope. =for apidoc Ams||LEAVE_with_name(name) Same as C<L</LEAVE>>, but when debugging is enabled it first checks that the -scope has the given name. C<name> must be a C<NUL>-terminated literal string. +scope has the given name. C<name> must be a literal string. =cut */ -- Perl5 Master Repository
