Document PERL_VERSION and kin as deprecated

Code should be removing these.  This documents them and gives the
preferred alternative to using them.

diff --git a/patchlevel.h b/patchlevel.h
index fb0d028..598a928 100644 (file)
--- a/patchlevel.h
+++ b/patchlevel.h
@@ -8,6 +8,32 @@
  *
  */
 
+/*
+=head1 Handy Values
+
+=for apidoc AmDnU|U8|PERL_REVISION
+The major number component of the perl interpreter currently being compiled or
+executing.  This has been C<5> from 1993 into 2020.
+
+Instead use one of the version comparison macros.  See C<L</PERL_VERSION_EQ>>.
+
+=for apidoc AmDnU|U8|PERL_VERSION
+The minor number component of the perl interpreter currently being compiled or
+executing.  Between 1993 into 2020, this has ranged from 0 to 33.
+
+Instead use one of the version comparison macros.  See C<L</PERL_VERSION_EQ>>.
+
+=for apidoc AmDnU|U8|PERL_SUBVERSION
+The micro number component of the perl interpreter currently being compiled or
+executing.  In stable releases this gives the dot release number for
+maintenance updates.  In development releases this gives a tag for a snapshot
+of the status at various points in the development cycle.
+
+Instead use one of the version comparison macros.  See C<L</PERL_VERSION_EQ>>.
+
+=cut
+*/
+
 #ifndef __PATCHLEVEL_H_INCLUDED__
 
 /* do not adjust the whitespace! Configure expects the numbers to be