From d4e99c76278c7e400307b1a7ceeb3b27676dfd3d Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Tue, 30 Apr 2013 08:39:44 -0600 Subject: autodoc.pl: Add note for deprecated functions This causes each deprecated function to have a prominent note to that effect in its API documentation. --- autodoc.pl | 10 +++++++++- mg.c | 4 +--- utf8.c | 6 ------ 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/autodoc.pl b/autodoc.pl index 925f2f541f..7f60443cd7 100644 --- a/autodoc.pl +++ b/autodoc.pl @@ -113,6 +113,7 @@ DOC: if ($docref and %$docref) { $embed_where = $docref->{flags} =~ /A/ ? 'api' : 'guts'; $embed_may_change = $docref->{flags} =~ /M/; + $flags .= 'D' if $docref->{flags} =~ /D/; } else { $missing{$name} = $file; } @@ -171,8 +172,15 @@ sub docout ($$$) { # output the docs for one function my($flags, $docs, $ret, $file, @args) = @$docref; $name =~ s/\s*$//; - $docs .= "NOTE: this function is experimental and may change or be + if ($flags =~ /D/) { + $docs = "\n\nDEPRECATED! It is planned to remove this function from a +future release of Perl. Do not use it for new code; remove it from +existing code.\n\n$docs"; + } + else { + $docs .= "NOTE: this function is experimental and may change or be removed without notice.\n\n" if $flags =~ /x/; + } $docs .= "NOTE: the perl_ form of this function is deprecated.\n\n" if $flags =~ /p/; $docs .= "NOTE: this function must be explicitly called as Perl_$name with an aTHX_ parameter.\n\n" diff --git a/mg.c b/mg.c index 6b8984ecd2..5f0f75852e 100644 --- a/mg.c +++ b/mg.c @@ -286,9 +286,7 @@ Perl_mg_set(pTHX_ SV *sv) /* =for apidoc mg_length -This function is deprecated. - -It reports on the SV's length in bytes, calling length magic if available, +Reports on the SV's length in bytes, calling length magic if available, but does not set the UTF8 flag on the sv. It will fall back to 'get' magic if there is no 'length' magic, but with no indication as to whether it called 'get' magic. It assumes the sv is a PVMG or diff --git a/utf8.c b/utf8.c index 90d0722ca7..04b06ed36b 100644 --- a/utf8.c +++ b/utf8.c @@ -338,8 +338,6 @@ Perl_is_utf8_char_buf(const U8 *buf, const U8* buf_end) /* =for apidoc is_utf8_char -DEPRECATED! - Tests if some arbitrary number of bytes begins in a valid UTF-8 character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC machines) character is a valid UTF-8 character. The actual number of bytes in the UTF-8 @@ -946,8 +944,6 @@ Perl_valid_utf8_to_uvchr(pTHX_ const U8 *s, STRLEN *retlen) /* =for apidoc utf8_to_uvchr -DEPRECATED! - Returns the native 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 length, in bytes, of that character. @@ -1047,8 +1043,6 @@ Perl_valid_utf8_to_uvuni(pTHX_ const U8 *s, STRLEN *retlen) /* =for apidoc utf8_to_uvuni -DEPRECATED! - 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 length, in bytes, of that character. -- cgit v1.2.1