From 87cea99e29dc843a5ce7742434c86a627eb3f6f5 Mon Sep 17 00:00:00 2001 From: Marcus Holland-Moritz Date: Wed, 29 Oct 2008 20:39:43 +0000 Subject: [PATCH] Remove redundant API definitions from '=for apidoc' sections. Those are already in embed.fnc, and most of them were already outdated. This also fixes the docs for pv_escape and pv_pretty. p4raw-id: //depot/perl@34642 --- dump.c | 9 ++------- pod/perlapi.pod | 13 +------------ pod/perlintern.pod | 2 +- utf8.c | 48 ++++++++++++++++++++++++------------------------ 4 files changed, 28 insertions(+), 44 deletions(-) diff --git a/dump.c b/dump.c index 7e48ae7..3a34fcb 100644 --- a/dump.c +++ b/dump.c @@ -169,9 +169,7 @@ Perl_dump_eval(pTHX) /* -=for apidoc Apd|char*|pv_escape|NN SV *dsv|NN const char const *str\ - |const STRLEN count|const STRLEN max - |STRLEN const *escaped, const U32 flags +=for apidoc pv_escape Escapes at most the first "count" chars of pv and puts the results into dsv such that the size of the escaped string will not exceed "max" chars @@ -308,10 +306,7 @@ Perl_pv_escape( pTHX_ SV *dsv, char const * const str, return SvPVX(dsv); } /* -=for apidoc Apd|char *|pv_pretty|NN SV *dsv|NN const char const *str\ - |const STRLEN count|const STRLEN max\ - |const char const *start_color| const char const *end_color\ - |const U32 flags +=for apidoc pv_pretty Converts a string into something presentable, handling escaping via pv_escape() and supporting quoting and ellipses. diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 8b47295..0738dfb 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -237,7 +237,7 @@ X Returns the highest index in the array. The number of elements in the array is C. Returns -1 if the array is empty. - I32 av_len(const AV *av) + I32 av_len(AV *av) =for hackers Found in file av.c @@ -836,9 +836,6 @@ Found in file dump.c =item pv_escape X - |const STRLEN count|const STRLEN max - |STRLEN const *escaped, const U32 flags - Escapes at most the first "count" chars of pv and puts the results into dsv such that the size of the escaped string will not exceed "max" chars and will not contain any incomplete escape sequences. @@ -873,8 +870,6 @@ sequences, whereas '%' is not a particularly common character in patterns. Returns a pointer to the escaped text as held by dsv. -NOTE: the perl_ form of this function is deprecated. - char* pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags) =for hackers @@ -883,10 +878,6 @@ Found in file dump.c =item pv_pretty X - |const STRLEN count|const STRLEN max\ - |const char const *start_color| const char const *end_color\ - |const U32 flags - Converts a string into something presentable, handling escaping via pv_escape() and supporting quoting and ellipses. @@ -906,8 +897,6 @@ any quotes or ellipses. Returns a pointer to the prettified text as held by dsv. -NOTE: the perl_ form of this function is deprecated. - char* pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags) =for hackers diff --git a/pod/perlintern.pod b/pod/perlintern.pod index daa62a9..48c3a7b 100644 --- a/pod/perlintern.pod +++ b/pod/perlintern.pod @@ -1092,7 +1092,7 @@ The name is returned as a mortal SV. Assumes that PL_op is the op that originally triggered the error, and that PL_comppad/PL_curpad points to the currently executing pad. - SV* find_uninit_var(OP* obase, SV* uninit_sv, bool top) + SV* find_uninit_var(const OP *const obase, const SV *const uninit_sv, bool top) =for hackers Found in file sv.c diff --git a/utf8.c b/utf8.c index 45f6a1d..08fc541 100644 --- a/utf8.c +++ b/utf8.c @@ -44,7 +44,7 @@ Unicode characters as a variable number of bytes, in such a way that characters in the ASCII range are unmodified, and a zero byte never appears within non-zero characters. -=for apidoc A|U8 *|uvuni_to_utf8_flags|U8 *d|UV uv|UV flags +=for apidoc uvuni_to_utf8_flags Adds the UTF-8 representation of the Unicode codepoint C to the end of the string C; C should be have at least C free @@ -237,7 +237,7 @@ S_is_utf8_char_slow(const U8 *s, const STRLEN len) } /* -=for apidoc A|STRLEN|is_utf8_char|const U8 *s +=for apidoc is_utf8_char Tests if some arbitrary number of bytes begins in a valid UTF-8 character. Note that an INVARIANT (i.e. ASCII) character is a valid @@ -260,7 +260,7 @@ Perl_is_utf8_char(pTHX_ const U8 *s) } /* -=for apidoc A|bool|is_utf8_string|const U8 *s|STRLEN len +=for apidoc is_utf8_string Returns true if first C bytes of the given string form a valid UTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does @@ -317,7 +317,7 @@ Perl_is_utf8_string(pTHX_ const U8 *s, STRLEN len) /* Implemented as a macro in utf8.h -=for apidoc A|bool|is_utf8_string_loc|const U8 *s|STRLEN len|const U8 **ep +=for apidoc is_utf8_string_loc Like is_utf8_string() but stores the location of the failure (in the case of "utf8ness failure") or the location s+len (in the case of @@ -325,7 +325,7 @@ case of "utf8ness failure") or the location s+len (in the case of See also is_utf8_string_loclen() and is_utf8_string(). -=for apidoc A|bool|is_utf8_string_loclen|const U8 *s|STRLEN len|const U8 **ep|const STRLEN *el +=for apidoc is_utf8_string_loclen Like is_utf8_string() but stores the location of the failure (in the case of "utf8ness failure") or the location s+len (in the case of @@ -384,7 +384,7 @@ Perl_is_utf8_string_loclen(pTHX_ const U8 *s, STRLEN len, const U8 **ep, STRLEN /* -=for apidoc A|UV|utf8n_to_uvuni|const U8 *s|STRLEN curlen|STRLEN *retlen|U32 flags +=for apidoc utf8n_to_uvuni Bottom level UTF-8 decode routine. Returns the Unicode code point value of the first character in the string C @@ -613,7 +613,7 @@ malformed: } /* -=for apidoc A|UV|utf8_to_uvchr|const U8 *s|STRLEN *retlen +=for apidoc utf8_to_uvchr Returns the native character value of the first character in the string C which is assumed to be in UTF-8 encoding; C will be set to the @@ -635,7 +635,7 @@ Perl_utf8_to_uvchr(pTHX_ const U8 *s, STRLEN *retlen) } /* -=for apidoc A|UV|utf8_to_uvuni|const U8 *s|STRLEN *retlen +=for apidoc utf8_to_uvuni Returns the Unicode code point of the first character in the string C which is assumed to be in UTF-8 encoding; C will be set to the @@ -661,7 +661,7 @@ Perl_utf8_to_uvuni(pTHX_ const U8 *s, STRLEN *retlen) } /* -=for apidoc A|STRLEN|utf8_length|const U8 *s|const U8 *e +=for apidoc utf8_length Return the length of the UTF-8 char encoded string C in characters. Stops at C (inclusive). If C s> or if the scan would end @@ -706,7 +706,7 @@ Perl_utf8_length(pTHX_ const U8 *s, const U8 *e) } /* -=for apidoc A|IV|utf8_distance|const U8 *a|const U8 *b +=for apidoc utf8_distance Returns the number of UTF-8 characters between the UTF-8 pointers C and C. @@ -726,7 +726,7 @@ Perl_utf8_distance(pTHX_ const U8 *a, const U8 *b) } /* -=for apidoc A|U8 *|utf8_hop|U8 *s|I32 off +=for apidoc utf8_hop Return the UTF-8 pointer C displaced by C characters, either forward or backward. @@ -763,7 +763,7 @@ Perl_utf8_hop(pTHX_ const U8 *s, I32 off) } /* -=for apidoc A|U8 *|utf8_to_bytes|U8 *s|STRLEN *len +=for apidoc utf8_to_bytes Converts a string C of length C from UTF-8 into byte encoding. Unlike C, this over-writes the original string, and @@ -808,7 +808,7 @@ Perl_utf8_to_bytes(pTHX_ U8 *s, STRLEN *len) } /* -=for apidoc A|U8 *|bytes_from_utf8|const U8 *s|STRLEN *len|bool *is_utf8 +=for apidoc bytes_from_utf8 Converts a string C of length C from UTF-8 into byte encoding. Unlike C but like C, returns a pointer to @@ -865,7 +865,7 @@ Perl_bytes_from_utf8(pTHX_ const U8 *s, STRLEN *len, bool *is_utf8) } /* -=for apidoc A|U8 *|bytes_to_utf8|const U8 *s|STRLEN *len +=for apidoc bytes_to_utf8 Converts a string C of length C from ASCII into UTF-8 encoding. Returns a pointer to the newly-created string, and sets C to @@ -1439,7 +1439,7 @@ Perl_is_utf8_mark(pTHX_ const U8 *p) } /* -=for apidoc A|UV|to_utf8_case|U8 *p|U8* ustrp|STRLEN *lenp|SV **swash|char *normal|char *special +=for apidoc to_utf8_case The "p" contains the pointer to the UTF-8 string encoding the character that is being converted. @@ -1554,7 +1554,7 @@ Perl_to_utf8_case(pTHX_ const U8 *p, U8* ustrp, STRLEN *lenp, } /* -=for apidoc A|UV|to_utf8_upper|const U8 *p|U8 *ustrp|STRLEN *lenp +=for apidoc to_utf8_upper Convert the UTF-8 encoded character at p to its uppercase version and store that in UTF-8 in ustrp and its length in bytes in lenp. Note @@ -1578,7 +1578,7 @@ Perl_to_utf8_upper(pTHX_ const U8 *p, U8* ustrp, STRLEN *lenp) } /* -=for apidoc A|UV|to_utf8_title|const U8 *p|U8 *ustrp|STRLEN *lenp +=for apidoc to_utf8_title Convert the UTF-8 encoded character at p to its titlecase version and store that in UTF-8 in ustrp and its length in bytes in lenp. Note @@ -1602,7 +1602,7 @@ Perl_to_utf8_title(pTHX_ const U8 *p, U8* ustrp, STRLEN *lenp) } /* -=for apidoc A|UV|to_utf8_lower|const U8 *p|U8 *ustrp|STRLEN *lenp +=for apidoc to_utf8_lower Convert the UTF-8 encoded character at p to its lowercase version and store that in UTF-8 in ustrp and its length in bytes in lenp. Note @@ -1626,7 +1626,7 @@ Perl_to_utf8_lower(pTHX_ const U8 *p, U8* ustrp, STRLEN *lenp) } /* -=for apidoc A|UV|to_utf8_fold|const U8 *p|U8 *ustrp|STRLEN *lenp +=for apidoc to_utf8_fold Convert the UTF-8 encoded character at p to its foldcase version and store that in UTF-8 in ustrp and its length in bytes in lenp. Note @@ -2167,7 +2167,7 @@ S_swash_get(pTHX_ SV* swash, UV start, UV span) } /* -=for apidoc A|U8 *|uvchr_to_utf8|U8 *d|UV uv +=for apidoc uvchr_to_utf8 Adds the UTF-8 representation of the Native codepoint C to the end of the string C; C should be have at least C free @@ -2203,7 +2203,7 @@ Perl_uvchr_to_utf8_flags(pTHX_ U8 *d, UV uv, UV flags) } /* -=for apidoc A|UV|utf8n_to_uvchr|U8 *s|STRLEN curlen|STRLEN *retlen|U32 +=for apidoc utf8n_to_uvchr flags Returns the native character value of the first character in the string @@ -2230,7 +2230,7 @@ U32 flags) } /* -=for apidoc A|char *|pv_uni_display|SV *dsv|U8 *spv|STRLEN len|STRLEN pvlim|UV flags +=for apidoc pv_uni_display Build to the scalar dsv a displayable version of the string spv, length len, the displayable version being at most pvlim bytes long @@ -2309,7 +2309,7 @@ Perl_pv_uni_display(pTHX_ SV *dsv, const U8 *spv, STRLEN len, STRLEN pvlim, UV f } /* -=for apidoc A|char *|sv_uni_display|SV *dsv|SV *ssv|STRLEN pvlim|UV flags +=for apidoc sv_uni_display Build to the scalar dsv a displayable version of the scalar sv, the displayable version being at most pvlim bytes long @@ -2331,7 +2331,7 @@ Perl_sv_uni_display(pTHX_ SV *dsv, SV *ssv, STRLEN pvlim, UV flags) } /* -=for apidoc A|I32|ibcmp_utf8|const char *s1|char **pe1|register UV l1|bool u1|const char *s2|char **pe2|register UV l2|bool u2 +=for apidoc ibcmp_utf8 Return true if the strings s1 and s2 differ case-insensitively, false if not (if they are equal case-insensitively). If u1 is true, the -- 2.7.4