[commit: base] master: New gcd documentation (5669f51)

[Ian Lynagh]

Repository : ssh://darcs.haskell.org//srv/darcs/packages/base

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/5669f51e8bb1c0e57ada08e0962e015bf90dcbc9

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

commit 5669f51e8bb1c0e57ada08e0962e015bf90dcbc9
Author: Daniel Fischer <daniel.is.fischer at googlemail.com>
Date:   Sun May 29 19:33:57 2011 +0200

    New gcd documentation
    
    Based on Ross Paterson's suggestion, a short explanation of the
    meaning of gcd, and a mention of possible negative results.

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

 GHC/Real.lhs |   12 +++++++++---
 1 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/GHC/Real.lhs b/GHC/Real.lhs
index 51d7db4..27b1b6c 100644
--- a/GHC/Real.lhs
+++ b/GHC/Real.lhs
@@ -520,9 +520,15 @@ x ^^ n          =  if n >= 0 then x^n else recip (x^(negate n))
                   in if even e then (nn :% dd) else (negate nn :% dd)
 
 -------------------------------------------------------
--- | @'gcd' x y@ is the greatest (nonnegative) integer that divides both @x@
--- and @y@; for example @'gcd' (-3) 6@ = @3@, @'gcd' (-3) (-6)@ = @3@,
--- @'gcd' 0 4@ = @4 at .  @'gcd' 0 0@ = @0 at .
+-- | @'gcd' x y@ is the non-negative factor of both @x@ and @y@ of which
+-- every common factor of @x@ and @y@ is also a factor; for example
+-- @'gcd' 4 2 = 2@, @'gcd' (-4) 6 = 2@, @'gcd' 0 4@ = @4 at . @'gcd' 0 0@ = @0 at .
+-- (That is, the common divisor that is \"greatest\" in the divisibility
+-- preordering.)
+--
+-- Note: Since for signed fixed-width integer types, @'abs' 'minBound' < 0@,
+-- the result may be negative if one of the arguments is @'minBound'@ (and
+-- necessarily is if the other is @0@ or @'minBound'@) for such types.
 gcd             :: (Integral a) => a -> a -> a
 gcd x y         =  gcd' (abs x) (abs y)
                    where gcd' a 0  =  a