Document API according to column-major ordering. (#41)

Adjust various typos / infelicities in documentation.

Author: dmjio

src/ArrayFire.hs

@@ -97,14 +97,17 @@ import Data.Word
 -- import qualified ArrayFire as A
 --
 -- main :: IO ()
--- main = print $ A.matrix @Double (2,2) [[1,2],[3,4]]
+-- main = print $ A.matrix @Double (3,2) [[1,2,3],[4,5,6]]
 -- @
 --
+-- Each 'Array' is constructed and displayed in column-major order.
+--
 -- @
 -- ArrayFire Array
--- [2 2 1 1]
---     1.0000     2.0000
---     3.0000     4.0000
+-- [3 2 1 1]
+--    1.0000     4.0000
+--    2.0000     5.0000
+--    3.0000     6.0000
 -- @
 
 -- $modules
@@ -128,7 +131,7 @@ import Data.Word
 -- main = A.printArray action \`catch\` (\\(e :: A.AFException) -> print e)
 --   where
 --     action =
---       A.matrix \@Double (3,3) [[[1..],[1..],[1..]]]
+--       A.matrix \@Double (3,3) [[1..],[1..],[1..]]
 --         \`A.mul\` A.matrix \@Double (2,2) [[1..],[1..]]
 -- @
 --
@@ -140,6 +143,8 @@ import Data.Word
 -- $construction
 -- An 'Array' can be constructed using the following smart constructors:
 --
+-- /Note/: All smart constructors (and ArrayFire internally) assume column-major order.
+--
 -- @
 -- >>> scalar \@Double 2.0
 -- ArrayFire Array
@@ -151,15 +156,24 @@ import Data.Word
 -- >>> vector \@Double 10 [1..]
 -- ArrayFire Array
 -- [10 1 1 1]
---    1.0000     2.0000     3.0000     4.0000     5.0000     6.0000     7.0000     8.0000     9.0000    10.0000
+--     1.0000
+--     2.0000
+--     3.0000
+--     4.0000
+--     5.0000
+--     6.0000
+--     7.0000
+--     8.0000
+--     9.0000
+--    10.0000
 -- @
 --
 -- @
 -- >>> matrix \@Double (2,2) [[1,2],[3,4]]
 -- ArrayFire Array
 -- [2 2 1 1]
---    1.0000     2.0000
---    3.0000     4.0000
+--     1.0000     3.0000
+--     2.0000     4.0000
 -- @
 --
 -- @
@@ -193,18 +207,27 @@ import Data.Word
 --
 -- Array construction can use Haskell's lazy lists, since 'take' is called on each dimension before sending to the C API.
 --
--- >>> mkArray @Double [2,2] [ [1..], [1..] ]
+-- >>> mkArray @Double [5,3] [1..]
 -- ArrayFire Array
--- [10 1 1 1]
---     1.0000     2.0000     3.0000     4.0000     5.0000     6.0000     7.0000     8.0000     9.0000    10.0000
---
--- Specifying up to 4 dimensions is allowed (anything high is ignored).
+-- [5 3 1 1]
+--    1.0000     6.0000    11.0000
+--    2.0000     7.0000    12.0000
+--    3.0000     8.0000    13.0000
+--    4.0000     9.0000    14.0000
+--    5.0000    10.0000    15.0000
+--
+-- Specifying up to 4 dimensions is allowed (anything higher is ignored).
 
 -- $laws
--- Every 'Array' is an instance of 'Eq', 'Num', 'Fractional', 'Floating'
+-- Every 'Array' has an instance of 'Eq', 'Num', 'Fractional', 'Floating' and 'Show'
 --
 -- 'Num'
 --
+-- >>> 2.0 :: Array Double
+-- ArrayFire Array
+-- [1 1 1 1]
+--    2.0000
+--
 -- >>> scalar @Int 1 + scalar @Int 1
 -- ArrayFire Array
 -- [1 1 1 1]
@@ -240,17 +263,40 @@ import Data.Word
 -- >>> scalar @Double 1 [10] /= scalar @Double 1 [10]
 -- False
 --
---
 -- 'Floating'
 --
 -- >>> pi :: Array Double
 -- ArrayFire Array
 -- [1 1 1 1]
 --    3.1416
 --
+-- >>> A.sqrt pi :: Array Double
+-- ArrayFire Array
+-- [1 1 1 1]
+--    1.7725
+--
+-- 'Fractional'
+--
+-- >>> (pi :: Array Double) / pi
+-- ArrayFire Array
+-- [1 1 1 1]
+--    1.000
+--
+-- >>> recip 0.5 :: Array Double
+-- ArrayFire Array
+-- [1 1 1 1]
+--    2.000
+--
+-- 'Show'
+--
+-- >>> 0.0 :: Array Double
+-- ArrayFire Array
+-- [1 1 1 1]
+--    0.000
+--
 
 -- $conversion
--- 'Array' can be exported into Haskell using `toVector'. This will create a Storable vector suitable for use in other C programs.
+-- Any 'Array' can be exported into Haskell using `toVector'. This will create a Storable vector suitable for use in other C programs.
 --
 -- >>> vector :: Vector Double <- toVector <$> randu @Double [10,10]
 --
@@ -271,9 +317,9 @@ import Data.Word
 --     array <- A.'readArrayKey' "file.array" "key"
 --     'print' array
 --
--- ArrayFire Array
--- [ 1 1 1 1 ]
---         10
+-- -- ArrayFire Array
+-- -- [ 1 1 1 1 ]
+-- --         10
 -- @
 --
 
@@ -287,6 +333,6 @@ import Data.Word
 --
 
 -- $visualization
--- The ArrayFire API is able to visualize
+-- The ArrayFire API is able to display visualizations using the Forge library
 -- >>> window <- createWindow 800 600 "Histogram"
 --