Better documentation for internal SV types

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index d1e179a..5a2124c 100644 (file)
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -604,17 +604,13 @@ macro and then check the return value.
 
 The most useful types that will be returned are:
 
-    SVt_IV    Scalar
-    SVt_NV    Scalar
-    SVt_PV    Scalar
-    SVt_RV    Scalar
-    SVt_PVAV  Array
-    SVt_PVHV  Hash
-    SVt_PVCV  Code
-    SVt_PVGV  Glob (possibly a file handle)
-    SVt_PVMG  Blessed or Magical Scalar
-
-See the F<sv.h> header file for more details.
+    < SVt_PVAV  Scalar
+    SVt_PVAV    Array
+    SVt_PVHV    Hash
+    SVt_PVCV    Code
+    SVt_PVGV    Glob (possibly a file handle)
+
+See L<perlapi/svtype> for more details.
 
 =head2 Blessed References and Class Objects
 

diff --git a/sv.h b/sv.h
index 4cac64a..d751be6 100644 (file)
--- a/sv.h
+++ b/sv.h
@@ -19,26 +19,101 @@
 An enum of flags for Perl types.  These are found in the file B<sv.h>
 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
 
-=for apidoc AmU||SVt_PV
-Pointer type flag for scalars.  See C<svtype>.
+The types are:
+
+    SVt_NULL
+    SVt_BIND (unused)
+    SVt_IV
+    SVt_NV
+    SVt_RV
+    SVt_PV
+    SVt_PVIV
+    SVt_PVNV
+    SVt_PVMG
+    SVt_REGEXP
+    SVt_PVGV
+    SVt_PVLV
+    SVt_PVAV
+    SVt_PVHV
+    SVt_PVCV
+    SVt_PVFM
+    SVt_PVIO
+
+These are most easily explained from the bottom up.
+
+SVt_PVIO is for I/O objects, SVt_PVFM for formats, SVt_PVCV for
+subroutines, SVt_PVHV for hashes and SVt_PVAV for arrays.
+
+All the others are scalar types, that is, things that can be bound to a
+C<$> variable.  For these, the internal types are mostly orthogonal to
+types in the Perl language.
+
+Hence, checking C<< SvTYPE(sv) < SVt_PVAV >> is the best way to see whether
+something is a scalar.
+
+SVt_PVGV represents a typeglob.  If !SvFAKE(sv), then it is a real,
+incoercible typeglob.  If SvFAKE(sv), then it is a scalar to which a
+typeglob has been assigned.  Assigning to it again will stop it from being
+a typeglob.  SVt_PVLV represents a scalar that delegates to another scalar
+behind the scenes.  It is used, e.g., for the return value of C<substr> and
+for tied hash and array elements.  It can hold any scalar value, including
+a typeglob. SVt_REGEXP is for regular expressions.
+
+SVt_PVMG represents a "normal" scalar (not a typeglob, regular expression,
+or delegate).  Since most scalars do not need all the internal fields of a
+PVMG, we save memory by allocating smaller structs when possible.  All the
+other types are just simpler forms of SVt_PVMG, with fewer internal fields.
+ SVt_NULL can only hold undef.  SVt_IV can hold undef, an integer, or a
+reference.  (SVt_RV is an alias for SVt_IV, which exists for backward
+compatibility.)  SVt_NV can hold any of those or a double.  SVt_PV can only
+hold undef or a string.  SVt_PVIV is a superset of SVt_PV and SVt_IV.
+SVt_PVNV is similar.  SVt_PVMG can hold anything SVt_PVNV can hold, but it
+can, but does not have to, be blessed or magical.
+
+=for apidoc AmU||SVt_NULL
+Type flag for scalars.  See L</svtype>.
 
 =for apidoc AmU||SVt_IV
-Integer type flag for scalars.  See C<svtype>.
+Type flag for scalars.  See L</svtype>.
 
 =for apidoc AmU||SVt_NV
-Double type flag for scalars.  See C<svtype>.
+Type flag for scalars.  See L</svtype>.
+
+=for apidoc AmU||SVt_PV
+Type flag for scalars.  See L</svtype>.
+
+=for apidoc AmU||SVt_PVIV
+Type flag for scalars.  See L</svtype>.
+
+=for apidoc AmU||SVt_PVNV
+Type flag for scalars.  See L</svtype>.
 
 =for apidoc AmU||SVt_PVMG
-Type flag for blessed scalars.  See C<svtype>.
+Type flag for scalars.  See L</svtype>.
+
+=for apidoc AmU||SVt_REGEXP
+Type flag for regular expressions.  See L</svtype>.
+
+=for apidoc AmU||SVt_PVGV
+Type flag for typeglobs.  See L</svtype>.
+
+=for apidoc AmU||SVt_PVLV
+Type flag for scalars.  See L</svtype>.
 
 =for apidoc AmU||SVt_PVAV
-Type flag for arrays.  See C<svtype>.
+Type flag for arrays.  See L</svtype>.
 
 =for apidoc AmU||SVt_PVHV
-Type flag for hashes.  See C<svtype>.
+Type flag for hashes.  See L</svtype>.
 
 =for apidoc AmU||SVt_PVCV
-Type flag for code refs.  See C<svtype>.
+Type flag for subroutines.  See L</svtype>.
+
+=for apidoc AmU||SVt_PVFM
+Type flag for formats.  See L</svtype>.
+
+=for apidoc AmU||SVt_PVIO
+Type flag for I/O objects.  See L</svtype>.
 
 =cut
 */

diff --git a/t/porting/known_pod_issues.dat b/t/porting/known_pod_issues.dat
index 7745d46..109609d 100644 (file)
--- a/t/porting/known_pod_issues.dat
+++ b/t/porting/known_pod_issues.dat
@@ -1,4 +1,4 @@
-# This file is the data file for porting/podcheck.t.
+# This file is the data file for t/porting/podcheck.t.
 # There are three types of lines.
 # Comment lines are white-space only or begin with a '#', like this one.  Any
 #   changes you make to the comment lines will be lost when the file is
@@ -210,7 +210,7 @@ os2/os2/os2-rexx/dll/dll.pm Verbatim line length including indents exceeds 79 by
 os2/os2/os2-rexx/rexx.pm       Verbatim line length including indents exceeds 79 by    1
 pod/perl.pod   Verbatim line length including indents exceeds 79 by    8
 pod/perlaix.pod        Verbatim line length including indents exceeds 79 by    11
-pod/perlapi.pod        ? Should you be using L<...> instead of 84
+pod/perlapi.pod        ? Should you be using L<...> instead of 77
 pod/perlapi.pod        Verbatim line length including indents exceeds 79 by    6
 pod/perlapi.pod        unresolved internal link        3
 pod/perlapio.pod       Verbatim line length including indents exceeds 79 by    5