Describe Castable philosophyHEADmaster

1 files changed, 6 insertions, 0 deletions

diff --git a/src/Data/Array/Nested/Convert.hs b/src/Data/Array/Nested/Convert.hs
index beb978e..cea2489 100644
--- a/src/Data/Array/Nested/Convert.hs
+++ b/src/Data/Array/Nested/Convert.hs
@@ -104,6 +104,12 @@ shxFromShS (n :$$ sh) = SKnown n :$% shxFromShS sh
 -- @'@: 'CastXS'' and 'CastXX''. For the other constructors, the types ensure
 -- that the shapes are already compatible. To convert between 'Ranked' and
 -- 'Shaped', go via 'Mixed'.
+--
+-- The guiding principle behind 'Castable' is that it should represent the
+-- array restructurings, or perhaps re-presentations, that do not change the
+-- underlying 'XArray's. This leads to the inclusion of some operations that do
+-- not look like a cast at first glance, like 'CastZip'; with the underlying
+-- representation in mind, however, they are very much like a cast.
 data Castable a b where
   CastId  :: Castable a a
   CastCmp :: Castable b c -> Castable a b -> Castable a c