Clarify Data.Data documentation
authorDavid Feuer <david.feuer@gmail.com>
Wed, 13 Sep 2017 12:22:42 +0000 (08:22 -0400)
committerBen Gamari <ben@smart-cactus.org>
Wed, 13 Sep 2017 14:39:56 +0000 (10:39 -0400)
Explain much more clearly when `dataCast1` and `dataCast2` can
have non-trivial implementations. On a couple different occasions,
I have attempted to write better defaults for these, only to
discover that we can't really do that. The new documentation
implicitly explains why that is.

[skip ci]

Reviewers: austin, hvr, bgamari, angerman

Reviewed By: bgamari, angerman

Subscribers: angerman, rwbarton, thomie

Differential Revision: https://phabricator.haskell.org/D3926

libraries/base/Data/Data.hs

index 33e8c86..a120980 100644 (file)
@@ -277,22 +277,34 @@ class Typeable a => Data a where
 ------------------------------------------------------------------------------
 
   -- | Mediate types and unary type constructors.
-  -- In 'Data' instances of the form @T a@, 'dataCast1' should be defined
-  -- as 'gcast1'.
+  --
+  -- In 'Data' instances of the form
+  --
+  -- @
+  --     instance (Data a, ...) => Data (T a)
+  -- @
+  --
+  -- 'dataCast1' should be defined as 'gcast1'.
   --
   -- The default definition is @'const' 'Nothing'@, which is appropriate
-  -- for non-unary type constructors.
+  -- for instances of other forms.
   dataCast1 :: Typeable t
             => (forall d. Data d => c (t d))
             -> Maybe (c a)
   dataCast1 _ = Nothing
 
   -- | Mediate types and binary type constructors.
-  -- In 'Data' instances of the form @T a b@, 'dataCast2' should be
-  -- defined as 'gcast2'.
+  --
+  -- In 'Data' instances of the form
+  --
+  -- @
+  --     instance (Data a, Data b, ...) => Data (T a b)
+  -- @
+  --
+  -- 'dataCast2' should be defined as 'gcast2'.
   --
   -- The default definition is @'const' 'Nothing'@, which is appropriate
-  -- for non-binary type constructors.
+  -- for instances of other forms.
   dataCast2 :: Typeable t
             => (forall d e. (Data d, Data e) => c (t d e))
             -> Maybe (c a)