perlapi: Consolidate cop_hints_exists* entries

Making these a single entry makes perlapi more concise with less
repetition, and clarifies the similarities and distinctions between the
variant forms.

Doing this showed me that some details had been glossed over, which this
commit adds.

This commit also changes the formal parameter name for one macro from
"keypv" to "key" so all variants use the same names.

1 files changed, 26 insertions, 34 deletions

diff --git a/cop.h b/cop.h
index 8018cab6fa..8a5d6b3ad4 100644
--- a/cop.h
+++ b/cop.h
@@ -588,54 +588,46 @@ string/length pair.
     cophh_fetch_sv(CopHINTHASH_get(cop), key, hash, flags)
 
 /*
-=for apidoc Am|bool|cop_hints_exists_pvn|const COP *cop|const char *keypv|STRLEN keylen|U32 hash|U32 flags
+=for apidoc   Am|bool|cop_hints_exists_pvn|const COP *cop|const char *key|STRLEN keylen|U32 hash|U32 flags
+=for apidoc_item|bool|cop_hints_exists_pv |const COP *cop|const char *key              |U32 hash|U32 flags
+=for apidoc_item|bool|cop_hints_exists_pvs|const COP *cop|           "key"                      |U32 flags
+=for apidoc_item|bool|cop_hints_exists_sv |const COP *cop|        SV *key              |U32 hash|U32 flags
 
-Look up the hint entry in the cop C<cop> with the key specified by
-C<keypv> and C<keylen>.  If C<flags> has the C<COPHH_KEY_UTF8> bit set,
-the key octets are interpreted as UTF-8, otherwise they are interpreted
-as Latin-1.  C<hash> is a precomputed hash of the key string, or zero if
-it has not been precomputed.  Returns true if a value exists, and false
-otherwise.
-
-=cut
-*/
+These look up the hint entry in the cop C<cop> with the key specified by
+C<key> (and C<keylen> in the C<pvn> form), returning true if a value exists,
+and false otherwise.
 
-#define cop_hints_exists_pvn(cop, keypv, keylen, hash, flags) \
-    cophh_exists_pvn(CopHINTHASH_get(cop), keypv, keylen, hash, flags)
+The forms differ in how the key is specified.  In all forms, the key is pointed
+to by C<key>.
+In the plain C<pv> form, the key is a C language NUL-terminated string.
+In the C<pvs> form, the key is a C language string literal.
+In the C<pvn> form, an additional parameter, C<keylen>, specifies the length of
+the string, which hence, may contain embedded-NUL characters.
+In the C<sv> form, C<*key> is an SV, and the key is the PV extracted from that.
+using C<L</SvPV_const>>.
 
-/*
-=for apidoc Am|bool|cop_hints_exists_pvs|const COP *cop|"key"|U32 flags
+C<hash> is a precomputed hash of the key string, or zero if it has not been
+precomputed.  This parameter is omitted from the C<pvs> form, as it is computed
+automatically at compile time.
 
-Like L</cop_hints_exists_pvn>, but takes a literal string
-instead of a string/length pair, and no precomputed hash.
+The only flag currently used from the C<flags> parameter is C<COPHH_KEY_UTF8>.
+It is illegal to set this in the C<sv> form.  In the C<pv*> forms, it specifies
+whether the key octets are interpreted as UTF-8 (if set) or as Latin-1 (if
+cleared).  The C<sv> form uses the underlying SV to determine the UTF-8ness of
+the octets.
 
 =cut
 */
 
+#define cop_hints_exists_pvn(cop, key, keylen, hash, flags) \
+    cophh_exists_pvn(CopHINTHASH_get(cop), key, keylen, hash, flags)
+
 #define cop_hints_exists_pvs(cop, key, flags) \
     cophh_exists_pvs(CopHINTHASH_get(cop), key, flags)
 
-/*
-=for apidoc Am|bool|cop_hints_exists_pv|const COP *cop|const char *key|U32 hash|U32 flags
-
-Like L</cop_hints_exists_pvn>, but takes a nul-terminated string instead
-of a string/length pair.
-
-=cut
-*/
-
 #define cop_hints_exists_pv(cop, key, hash, flags) \
     cophh_exists_pv(CopHINTHASH_get(cop), key, hash, flags)
 
-/*
-=for apidoc Am|bool|cop_hints_exists_sv|const COP *cop|SV *key|U32 hash|U32 flags
-
-Like L</cop_hints_exists_pvn>, but takes a Perl scalar instead of a
-string/length pair.
-
-=cut
-*/
-
 #define cop_hints_exists_sv(cop, key, hash, flags) \
     cophh_exists_sv(CopHINTHASH_get(cop), key, hash, flags)