diff options
author | David Feuer <david.feuer@gmail.com> | 2017-09-13 08:22:42 -0400 |
---|---|---|
committer | Ben Gamari <ben@smart-cactus.org> | 2017-09-13 10:39:56 -0400 |
commit | f8e383f0e4f11e6e1060888208440907bcba9248 (patch) | |
tree | 7e0e7d92f94b97ee72ff2262cc06d9c596f9daad | |
parent | d645e441704a02b9eb5548e7c92cc5ee30a345ef (diff) | |
download | haskell-f8e383f0e4f11e6e1060888208440907bcba9248.tar.gz |
Clarify Data.Data documentation
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
-rw-r--r-- | libraries/base/Data/Data.hs | 24 |
1 files changed, 18 insertions, 6 deletions
diff --git a/libraries/base/Data/Data.hs b/libraries/base/Data/Data.hs index 33e8c86fe4..a120980c90 100644 --- a/libraries/base/Data/Data.hs +++ b/libraries/base/Data/Data.hs @@ -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) |