document deep coercions

3 files changed, 40 insertions, 9 deletions

diff --git a/TODO b/TODO
index 1c81bbc7..e5b98412 100644
--- a/TODO
+++ b/TODO
@@ -3,9 +3,6 @@
           * Tied - i.e. references to tied variables. Parameterized:
             Tied["Some::Package"]
           * steal from MooseX-Types-Ro?
-      * coercion
-          * Auto-coercion
-              * needs documenting
       * improve speed for non-inlineable type constraints and coercions
           * maybe use eval context idea from Type::Check
       * Type-Tiny could be used as a backend for Scalar::Does?
diff --git a/TODO.mm b/TODO.mm
index f2893640..4b129b6d 100644
--- a/TODO.mm
+++ b/TODO.mm
@@ -5,12 +5,6 @@
 <node CREATED="1365441792858" ID="ID_393588377" MODIFIED="1365441880404" TEXT="Tied - i.e. references to tied variables. Parameterized: Tied[&quot;Some::Package&quot;]"/>
 <node CREATED="1365442342382" ID="ID_345593149" MODIFIED="1365442365283" TEXT="steal from MooseX-Types-Ro?"/>
 </node>
-<node CREATED="1365529954377" ID="ID_1288968569" MODIFIED="1365533825483" POSITION="left" TEXT="coercion">
-<node CREATED="1365442049043" ID="ID_1920269603" MODIFIED="1365534968825" TEXT="Auto-coercion">
-<font NAME="SansSerif" SIZE="12"/>
-<node CREATED="1365529844572" ID="ID_700685078" MODIFIED="1365529849044" TEXT="needs documenting"/>
-</node>
-</node>
 <node CREATED="1365786093068" ID="ID_1062710536" MODIFIED="1366039141668" POSITION="left" TEXT="improve speed for non-inlineable type constraints and coercions">
 <node CREATED="1365786151311" ID="ID_213645694" LINK="#ID_962609536" MODIFIED="1365786201307" TEXT="maybe use eval context idea from Type::Check"/>
 </node>
diff --git a/lib/Type/Tiny/Manual/Coercions.pod b/lib/Type/Tiny/Manual/Coercions.pod
index 9348065c..f2327bc8 100644
--- a/lib/Type/Tiny/Manual/Coercions.pod
+++ b/lib/Type/Tiny/Manual/Coercions.pod
@@ -177,6 +177,46 @@ for C<plus_coercions>. The following two are the same:
    
    PathTiny->plus_constructors(Str, "new");
 
+=head2 "Deep" Coercions
+
+Certain parameterized type constraints can automatically acquire coercions
+if their parameters have coercions. For example:
+
+   ArrayRef[ Int->plus_coercions(Num, q{int($_)}) ]
+
+... does what you mean!
+
+The parameterized type constraints that do this magic include the following
+ones from L<Types::Standard>:
+
+=over
+
+=item *
+
+C<ScalarRef>
+
+=item *
+
+C<ArrayRef>
+
+=item *
+
+C<HashRef>
+
+=item *
+
+C<Tuple>
+
+=item *
+
+C<Dict>
+
+=item *
+
+C<Optional>
+
+=back
+
 =head1 SEE ALSO
 
 L<Moose::Manual::BestPractices>,