From 3aac5ebb1fea18c93b4bdc664e943a0e8983fc6f Mon Sep 17 00:00:00 2001
From: Nick Bowler <nbowler@draconx.ca>
Date: Thu, 19 Nov 2009 23:34:56 -0500
Subject: [PATCH] doc: Add a detailed overview of the purpose of the library.

---
 Data/Floating/Types.hs | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/Data/Floating/Types.hs b/Data/Floating/Types.hs
index 6c67ac4..0e0b3a3 100644
--- a/Data/Floating/Types.hs
+++ b/Data/Floating/Types.hs
@@ -1,5 +1,32 @@
--- | This module provides an alternate definition of the floating point types
--- in Haskell.
+-- | Alternate floating point types for Haskell.  The floating point support
+-- in the language is extremely lacking for a number of reasons (some more
+-- severe than others):
+--
+-- * There is no way to sanely convert between Haskell's floating types -- not
+-- even between Double and CDouble.  The 'realToFrac' function converts to
+-- 'Rational' which loses information about negative zeros, infinities and
+-- NaNs.
+--
+-- * Haskell's floating types are instances of 'Ord' (a class for totally
+-- ordered data types), despite the fact that floating point types are not
+-- totally ordered.  This class cannot express the fact that there are
+-- uncomparable elements.
+--
+-- * Functions that should probably care about negative zeros, such as
+-- 'signum' and 'abs', do not.
+--
+-- * Haskell's floating types have a non-sensical 'Enum' instance.
+--
+-- * The various rounding and truncation functions return integers rather than
+-- floating point values.  These functions return garbage for non-finite input
+-- and are useless for implementing floating point functions.
+--
+-- * There is no way to handle rounding modes or floating point exceptions.
+--
+-- * The selection of floating point library functions pales in comparison to
+-- C.
+--
+-- This package is intended to address all of these issues.
 {-# LANGUAGE MultiParamTypeClasses, FlexibleInstances, OverlappingInstances #-}
 {-# LANGUAGE ForeignFunctionInterface, MagicHash #-}
 {-# INCLUDE cfloat.h #-}
-- 
2.11.4.GIT