[GHC] #15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented

[GHC]

#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances
(e.g. Float) should be documented
-------------------------------------+-------------------------------------
        Reporter:  sjakobi           |                Owner:  (none)
            Type:  feature request   |               Status:  new
        Priority:  normal            |            Milestone:  8.6.1
       Component:  Core Libraries    |              Version:  8.4.2
      Resolution:                    |             Keywords:
Operating System:  Unknown/Multiple  |         Architecture:
                                     |  Unknown/Multiple
 Type of failure:  None/Unknown      |            Test Case:
      Blocked By:                    |             Blocking:
 Related Tickets:                    |  Differential Rev(s):
       Wiki Page:                    |
-------------------------------------+-------------------------------------

Comment (by dfeuer):

 That's perfectly documentation that Haddock will, sadly, chew up and turn
 into something almost completely unreadable. Ryan Scott thinks it's good
 to write documentation like that to drive Haddock development, but I'm not
 sure. As for what the customary laws ''are'', here's a rough draft:

 == `Eq`

 `Eq` is expected to be an equivalence relation, and values that compare
 "equal" should be indistinguishable (except perhaps when using an
 "private" interface).

  Reflexivity:: `x == x  =  True`
  Symmetry:: `x == y  =  y == x`
  Transitivity:: If `x == y && y == z = True`, then `x == z = True`
  Substitutivity:: If `x == y = True` and `f` is a "public" function, then
 `f x == f y = True`
  Negation:: `x /= y  =  not (x == y)`

 == `Ord`

 === Basics
  Transitivity:: If `x <= y && y <= z = True`, then `x <= z = True`
  Reflexivity:: relative to `==`: = True`
  Antisymmetry:: If `x <= y && y <= x = True`, then `x == y = True`

 === Operator interactions

 1. `x >= y = y <= x`
 2. `x < y = x <= y && x /= y`
 3. `x > y = y < x`
 4. `x < y = compare x y == LT`
 5. `x > y = compare x y == GT`
 6. `x == y = compare x y == EQ`

 The `max` and `min` rules look a bit funny. Note that `max x y` needn't be
 ''identical'' to either `x` or `y`; it just needs to ''look'' the same.

 7. `min x y == if x <= y then x else y  =  True`
 8. `max x y == if x >= y then x else y  =  True`

-- 
Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/15078#comment:1>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler