This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Change pod for macros that require "literal strings"
authorKarl Williamson <khw@cpan.org>
Sat, 31 Aug 2019 20:40:12 +0000 (14:40 -0600)
committerKarl Williamson <khw@cpan.org>
Tue, 3 Sep 2019 03:52:12 +0000 (21:52 -0600)
Now that Devel::PPPort  has the ability to handle these, we can loosen
the syntax for clarity.

cop.h
handy.h
hv.h
pad.h
scope.h

diff --git a/cop.h b/cop.h
index dfca7e4..00396f0 100644 (file)
--- a/cop.h
+++ b/cop.h
@@ -190,7 +190,7 @@ 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|"literal string" key|U32 flags
+=for apidoc Amx|SV *|cophh_fetch_pvs|const COPHH *cophh|"key"|U32 flags
 
 Like L</cophh_fetch_pvn>, but takes a literal string instead
 of a string/length pair, and no precomputed hash.
@@ -296,7 +296,7 @@ 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|"literal string" key|SV *value|U32 flags
+=for apidoc Amx|COPHH *|cophh_store_pvs|const COPHH *cophh|"key"|SV *value|U32 flags
 
 Like L</cophh_store_pvn>, but takes a literal string instead
 of a string/length pair, and no precomputed hash.
@@ -353,7 +353,7 @@ 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|"literal string" key|U32 flags
+=for apidoc Amx|COPHH *|cophh_delete_pvs|const COPHH *cophh|"key"|U32 flags
 
 Like L</cophh_delete_pvn>, but takes a literal string instead
 of a string/length pair, and no precomputed hash.
@@ -493,7 +493,7 @@ 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|"literal string" key|U32 flags
+=for apidoc Am|SV *|cop_hints_fetch_pvs|const COP *cop|"key"|U32 flags
 
 Like L</cop_hints_fetch_pvn>, but takes a literal string
 instead of a string/length pair, and no precomputed hash.
diff --git a/handy.h b/handy.h
index d180f2b..895456f 100644 (file)
--- a/handy.h
+++ b/handy.h
@@ -293,76 +293,76 @@ detects that and gets all excited. */
 /*
 =head1 SV Manipulation Functions
 
-=for apidoc Ama|SV*|newSVpvs|"literal string" s
+=for apidoc Ama|SV*|newSVpvs|"literal string"
 Like C<newSVpvn>, but takes a literal string instead of a
 string/length pair.
 
-=for apidoc Ama|SV*|newSVpvs_flags|"literal string" s|U32 flags
+=for apidoc Ama|SV*|newSVpvs_flags|"literal string"|U32 flags
 Like C<newSVpvn_flags>, but takes a literal string instead of
 a string/length pair.
 
-=for apidoc Ama|SV*|newSVpvs_share|"literal string" s
+=for apidoc Ama|SV*|newSVpvs_share|"literal string"
 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|"literal string" s|I32 flags
+=for apidoc Am|void|sv_catpvs_flags|SV* sv|"literal string"|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|"literal string" s
+=for apidoc Am|void|sv_catpvs_nomg|SV* sv|"literal string"
 Like C<sv_catpvn_nomg>, but takes a literal string instead of
 a string/length pair.
 
-=for apidoc Am|void|sv_catpvs|SV* sv|"literal string" s
+=for apidoc Am|void|sv_catpvs|SV* sv|"literal string"
 Like C<sv_catpvn>, but takes a literal string instead of a
 string/length pair.
 
-=for apidoc Am|void|sv_catpvs_mg|SV* sv|"literal string" s
+=for apidoc Am|void|sv_catpvs_mg|SV* sv|"literal string"
 Like C<sv_catpvn_mg>, but takes a literal string instead of a
 string/length pair.
 
-=for apidoc Am|void|sv_setpvs|SV* sv|"literal string" s
+=for apidoc Am|void|sv_setpvs|SV* sv|"literal string"
 Like C<sv_setpvn>, but takes a literal string instead of a
 string/length pair.
 
-=for apidoc Am|void|sv_setpvs_mg|SV* sv|"literal string" s
+=for apidoc Am|void|sv_setpvs_mg|SV* sv|"literal string"
 Like C<sv_setpvn_mg>, but takes a literal string instead of a
 string/length pair.
 
-=for apidoc Am|SV *|sv_setref_pvs|SV *const rv|const char *const classname|"literal string" s
+=for apidoc Am|SV *|sv_setref_pvs|SV *const rv|const char *const classname|"literal string"
 Like C<sv_setref_pvn>, but takes a literal string instead of
 a string/length pair.
 
 =head1 Memory Management
 
-=for apidoc Ama|char*|savepvs|"literal string" s
+=for apidoc Ama|char*|savepvs|"literal string"
 Like C<savepvn>, but takes a literal string instead of a
 string/length pair.
 
-=for apidoc Ama|char*|savesharedpvs|"literal string" s
+=for apidoc Ama|char*|savesharedpvs|"literal string"
 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|"literal string" name|I32 create
+=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 Am|SV**|hv_fetchs|HV* tb|"literal string" key|I32 lval
+=for apidoc Am|SV**|hv_fetchs|HV* tb|"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|"literal string" key|SV* val
+=for apidoc Am|SV**|hv_stores|HV* tb|"key"|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|"literal string" pv|U32 flags
+=for apidoc Amx|void|lex_stuff_pvs|"pv"|U32 flags
 
 Like L</lex_stuff_pvn>, but takes a literal string instead of
 a string/length pair.
@@ -455,7 +455,7 @@ Test two buffers (which may contain embedded C<NUL> characters, to see if they
 are equal.  The C<len> parameter indicates the number of bytes to compare.
 Returns zero if equal, or non-zero if non-equal.
 
-=for apidoc Am|bool|memEQs|char* s1|STRLEN l1|"literal string" s2
+=for apidoc Am|bool|memEQs|char* s1|STRLEN l1|"s2"
 Like L</memEQ>, but the second string is a literal enclosed in double quotes,
 C<l1> gives the number of bytes in C<s1>.
 Returns zero if equal, or non-zero if non-equal.
@@ -465,7 +465,7 @@ Test two buffers (which may contain embedded C<NUL> characters, to see if they
 are not equal.  The C<len> parameter indicates the number of bytes to compare.
 Returns zero if non-equal, or non-zero if equal.
 
-=for apidoc Am|bool|memNEs|char* s1|STRLEN l1|"literal string" s2
+=for apidoc Am|bool|memNEs|char* s1|STRLEN l1|"s2"
 Like L</memNE>, but the second string is a literal enclosed in double quotes,
 C<l1> gives the number of bytes in C<s1>.
 Returns zero if non-equal, or zero if non-equal.
diff --git a/hv.h b/hv.h
index 751cb20..607152c 100644 (file)
--- a/hv.h
+++ b/hv.h
@@ -575,7 +575,7 @@ struct refcounted_he {
 };
 
 /*
-=for apidoc m|SV *|refcounted_he_fetch_pvs|const struct refcounted_he *chain|"literal string" key|U32 flags
+=for apidoc m|SV *|refcounted_he_fetch_pvs|const struct refcounted_he *chain|"key"|U32 flags
 
 Like L</refcounted_he_fetch_pvn>, but takes a literal string
 instead of a string/length pair, and no precomputed hash.
@@ -587,7 +587,7 @@ 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|"literal string" key|SV *value|U32 flags
+=for apidoc m|struct refcounted_he *|refcounted_he_new_pvs|struct refcounted_he *parent|"key"|SV *value|U32 flags
 
 Like L</refcounted_he_new_pvn>, but takes a literal string
 instead of a string/length pair, and no precomputed hash.
diff --git a/pad.h b/pad.h
index 1c15d58..6b31ace 100644 (file)
--- a/pad.h
+++ b/pad.h
@@ -492,7 +492,7 @@ 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|"literal string" name|U32 flags|HV *typestash|HV *ourstash
+=for apidoc Am|PADOFFSET|pad_add_name_pvs|"name"|U32 flags|HV *typestash|HV *ourstash
 
 Exactly like L</pad_add_name_pvn>, but takes a literal string
 instead of a string/length pair.
@@ -504,7 +504,7 @@ 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|"literal string" name|U32 flags
+=for apidoc Am|PADOFFSET|pad_findmy_pvs|"name"|U32 flags
 
 Exactly like L</pad_findmy_pvn>, but takes a literal string
 instead of a string/length pair.
diff --git a/scope.h b/scope.h
index 5fde315..483bc5d 100644 (file)
--- a/scope.h
+++ b/scope.h
@@ -167,12 +167,12 @@ Opening bracket on a callback.  See C<L</LEAVE>> and L<perlcall>.
 =for apidoc Amns||LEAVE
 Closing bracket on a callback.  See C<L</ENTER>> and L<perlcall>.
 
-=for apidoc Ams||ENTER_with_name|const char * name
+=for apidoc Ams||ENTER_with_name|"name"
 
 Same as C<L</ENTER>>, but when debugging is enabled it also associates the
 given literal string with the new scope.
 
-=for apidoc Ams||LEAVE_with_name|const char * name
+=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 literal string.