[commit: ghc] master: Clarify Data.Data documentation (f8e383f)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/f8e383f0e4f11e6e1060888208440907bcba9248/ghc

>---------------------------------------------------------------

commit f8e383f0e4f11e6e1060888208440907bcba9248
Author: David Feuer <david.feuer at gmail.com>
Date:   Wed Sep 13 08:22:42 2017 -0400

    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


>---------------------------------------------------------------

f8e383f0e4f11e6e1060888208440907bcba9248
 libraries/base/Data/Data.hs | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/libraries/base/Data/Data.hs b/libraries/base/Data/Data.hs
index 33e8c86..a120980 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)