rewrite the 'is cached' section

Based on feedback from smls++

Author: Carl Masak

lib/Type/Routine.pod

@@ -63,11 +63,21 @@ Returns C<True> if the routine is a stub
 
     multi sub trait_mod:<is>(Routine $r, :$cached!)
 
-Caches the return value of a routine, which means that when several calls with
-the same argument lists are performed, only the first one actually calls the
-routine, and subsequent calls retrieve the return value from the cache.
+Causes the return value of a routine to be stored, so that when subsequent
+calls with the same list of arguments are made, the stored value can be
+returned immediately instead of re-running the routine.
 
-This makes only sense for routines that retrieve value types ase arguments.
+Useful when storing and returning the computed value is much faster than
+re-computing it every time, and when the time saving trumps the cost of the
+use of more memory.
+
+Even if the arguments passed to the routine are "reference types" (such as
+objects or arrays), then for the purpose of caching they will only be compared
+based on their contents. Thus the second invocation will hit the cache in this
+case:
+
+    say foo( [1, 2, 3] );   # runs foo
+    say foo( [1, 2, 3] );   # doesn't run foo, uses cached value
 
 =begin code
 use v6;