diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -10,7 +10,6 @@
 
 The module `Data.Matrix.MatrixMarket` exports the user interface:
 
-
     readMatrix :: FilePath -> IO (Matrix S.Scientific)
 
     readArray :: FilePath -> IO (Array S.Scientific)
@@ -21,7 +20,15 @@
 
 The first two functions contain the parsing logic, and make use of `scientific` for parsing numerical data in scientific notation.
 
-`test/LibSpec.hs` contains a simple read/write/read sanity test:
+
+### Naming convention
+
+We follow the MatrixMarket format definitions, by which a "Matrix" is _sparse_ and stored in coordinate format (row, column, entry), whereas an "Array" is a _dense_ grid of numbers, stored in column-oriented form.
+Algebraic vectors, such as the right-hand sides of equation systems, are stored as n-by-1 Arrays.
+
+## Testing
+
+`test/LibSpec.hs` contains a simple read/write/read sanity test for the included Matrix Marked data files (`fidapm05.mtx` and `fidapm05_rhs1.mtx`):
 
     m0 <- readMatrix fname   -- load original
     writeMatrix ftemp m0     -- save as temp
diff --git a/matrix-market-attoparsec.cabal b/matrix-market-attoparsec.cabal
--- a/matrix-market-attoparsec.cabal
+++ b/matrix-market-attoparsec.cabal
@@ -1,9 +1,9 @@
 name:                matrix-market-attoparsec
-version:             0.1.0.1
+version:             0.1.0.2
 synopsis:            Attoparsec parsers for the NIST Matrix Market format
 description:         Please see README.md
 homepage:            https://github.com/ocramz/matrix-market-attoparsec
-license:             BSD3
+license:             GPL-3
 license-file:        LICENSE
 author:              Marco Zocca
 maintainer:          zocca marco gmail
diff --git a/src/Data/Matrix/MatrixMarket.hs b/src/Data/Matrix/MatrixMarket.hs
--- a/src/Data/Matrix/MatrixMarket.hs
+++ b/src/Data/Matrix/MatrixMarket.hs
@@ -11,15 +11,25 @@
 -- Attoparsec parser and serializer for the NIST MatrixMarket format. The parser logic originally appeared in `accelerate-examples` and it is reused here (courtesy of T.McDonell and the `accelerate` developers) with some amendments.
 -- 
 -- In this version:
+
 -- *) Numbers are represented with Scientific notation instead of floating point
+
 -- *) Parsing rules are a bit relaxed to accommodate various whitespace corner cases
 --
 -----------------------------------------------------------------------------
-module Data.Matrix.MatrixMarket (module M, readMatrix, readArray,
+module Data.Matrix.MatrixMarket
+       (module M,
+        -- * Load
+        readMatrix, readArray,
+        -- * Save
         writeMatrix, writeArray,
+        -- 
         Matrix(..), Array(..),
         Format (Coordinate, Array), Structure (General, Symmetric, Hermitian, Skew),
+        -- * Helpers
+        -- ** Matrix-related
         nnz, dim, numDat,
+        -- ** Array-related
         dimArr, numDatArr) where
 
 import Data.Matrix.MatrixMarket.Internal as M
diff --git a/src/Data/Matrix/MatrixMarket/Internal.hs b/src/Data/Matrix/MatrixMarket/Internal.hs
--- a/src/Data/Matrix/MatrixMarket/Internal.hs
+++ b/src/Data/Matrix/MatrixMarket/Internal.hs
@@ -276,19 +276,21 @@
 
 -- | helpers
 
-
+-- | Number of matrix nonzeros
 nnz :: Matrix t -> Int
 nnz m = case m of (RMatrix _ nz _ _) -> nz
                   (CMatrix _ nz _ _) -> nz
                   (PatternMatrix _ nz _ _) -> nz
                   (IntMatrix _ nz _ _) -> nz
 
+-- | Matrix size : number of rows, number of columns
 dim :: Matrix t -> (Int, Int)
 dim m = case m of (RMatrix d _ _ _) -> d
                   (CMatrix d _ _ _) -> d
                   (PatternMatrix d _ _ _) -> d
                   (IntMatrix d _ _ _) -> d
 
+-- | Length of data vector internal to the Matrix; this is _not_ necessarily the actual number of matrix entries because symmetric entries are not stored 
 numDat :: Matrix t -> Int
 numDat m = case m of (RMatrix _ _ _ d) -> length d
                      (CMatrix _ _ _ d) -> length d
@@ -296,10 +298,12 @@
                      (IntMatrix _ _ _ d) -> length d
 
 
+-- | Array size : number of rows, number of columns
 dimArr :: Array t -> (Int, Int)
 dimArr a = case a of (RArray d _ _) -> d
                      (CArray d _ _) -> d
- 
+
+-- | Length of data vector internal to the Array; this is _not_ necessarily the actual number of matrix entries because symmetric entries are not stored 
 numDatArr :: Array a -> Int
 numDatArr a = case a of (RArray _ _ ll) -> length ll 
                         (CArray _ _ ll) -> length ll