autodoc.pl: Add note for deprecated functions

This causes each deprecated function to have a prominent note to that
effect in its API documentation.

diff --git a/autodoc.pl b/autodoc.pl
index 925f2f5..7f60443 100644 (file)
--- 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 6b8984e..5f0f758 100644 (file)
--- 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 90d0722..04b06ed 100644 (file)
--- 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<s>
 which is assumed to be in UTF-8 encoding; C<retlen> 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<s>
 which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
 length, in bytes, of that character.