Update documentation

CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog for the [`ghc-typelits-extra`](http://hackage.haskell.org/package/ghc-typelits-extra) package
+
+## 0.1
+* Initial release

HACKING.md

@@ -0,0 +1,31 @@
+#Hacking
+Download sources:
+```
+git clone https://github.com/christiaanb/ghc-typelits-extra.git
+git clone https://github.com/clash-lang/ghc-tcplugins-extra.git
+git clone https://github.com/clash-lang/ghc-typelits-natnormalise.git
+```
+
+Go to ghc-typelits-extra dir:
+```
+cd ghc-typelits-extra
+```
+
+Run:
+```
+cabal sandbox init
+cabal sandbox add-source ../ghc-typelits-extra
+cabal sandbox add-source ../ghc-typelits-natnormalise
+cabal install --dependencies-only --enable-tests
+```
+
+Configure the package with testing enabled:
+```
+cabal configure --enable-tests
+```
+
+Once you've finished hacking, build and test:
+```
+cabal build
+cabal test
+```

README.md

@@ -1,34 +1,10 @@
 # ghc-typelits-extra
-Extra type-level operations on GHC.TypeLits.Nat and a custom solver
 
-#Hacking
-Download sources:
-```
-git clone https://github.com/christiaanb/ghc-typelits-extra.git
-git clone https://github.com/clash-lang/ghc-tcplugins-extra.git
-git clone https://github.com/clash-lang/ghc-typelits-natnormalise.git
-```
+[![Build Status](https://secure.travis-ci.org/clash-lang/ghc-typelits-natnormalise.png?branch=master)](http://travis-ci.org/clash-lang/ghc-typelits-natnormalise)
+[![Hackage](https://img.shields.io/hackage/v/ghc-typelits-natnormalise.svg)](https://hackage.haskell.org/package/ghc-typelits-natnormalise)
+[![Hackage Dependencies](https://img.shields.io/hackage-deps/v/ghc-typelits-natnormalise.svg?style=flat)](http://packdeps.haskellers.com/feed?needle=exact%3Aghc-typelits-natnormalise)
 
-Go to ghc-typelits-extra dir:
-```
-cd ghc-typelits-extra
-```
+Extra type-level operations on GHC.TypeLits.Nat and a custom solver:
 
-Run:
-```
-cabal sandbox init
-cabal sandbox add-source ../ghc-typelits-extra
-cabal sandbox add-source ../ghc-typelits-natnormalise
-cabal install --dependencies-only --enable-tests
-```
-
-Configure the package with testing enabled:
-```
-cabal configure --enable-tests
-```
-
-Once you've finished hacking, build and test:
-```
-cabal build
-cabal test
-```
+* `GHC.TypeLits.Extra.GCD`: a type-level `gcd`
+* `GHC.TypeLits.Extra.CLog`: type-level equivalent of `clog x y = ceiling (logBase x y)`

ghc-typelits-extra.cabal

@@ -1,6 +1,23 @@
 name:                ghc-typelits-extra
-version:             0.1.0.0
+version:             0.1
 synopsis:            Additional type-level operations on GHC.TypeLits.Nat
+description:
+  Additional type-level operations on @GHC.TypeLits.Nat@:
+  .
+  * @GHC.TypeLits.Extra.GCD@: a type-level @gcd@
+  .
+  * @GHC.TypeLits.Extra.CLog@: type-level equivalent of
+    "@clog x y = ceiling (logBase x y)@"
+  .
+  And a custom solver for the above operations defined in
+  @GHC.TypeLits.Extra.Solver@ as a GHC type-checker plugin. To use the plugin,
+  add the
+  .
+  @
+  OPTIONS_GHC -fplugin GHC.TypeLits.Extra.Solver
+  @
+  .
+  pragma to the header of your file.
 homepage:            http://www.clash-lang.org/
 license:             BSD2
 license-file:        LICENSE
@@ -9,6 +26,8 @@ maintainer:          [email protected]
 copyright:           Copyright © 2015 University of Twente
 category:            Type System
 build-type:          Simple
+extra-source-files:  README.md
+                     CHANGELOG.md
 cabal-version:       >=1.10
 
 flag deverror

src/GHC/TypeLits/Extra.hs

@@ -1,17 +1,48 @@
 {-# LANGUAGE DataKinds    #-}
 {-# LANGUAGE TypeFamilies #-}
+
+{-# OPTIONS_HADDOCK show-extensions #-}
+
+{-|
+Copyright  :  (C) 2015, University of Twente
+License    :  BSD2 (see the file LICENSE)
+Maintainer :  Christiaan Baaij <[email protected]>
+
+Additional type-level operations on 'GHC.TypeLits.Nat':
+
+  * 'GCD': a type-level 'gcd'
+
+  * 'CLog': type-level equivalent of
+    \"@clog x y = 'ceiling' ('logBase' x y)@\"
+
+A custom solver for the above operations defined is defined in
+"GHC.TypeLits.Extra.Solver" as a GHC type-checker plugin. To use the plugin,
+add the
+
+@
+{\-\# OPTIONS_GHC -fplugin GHC.TypeLits.Extra.Solver \#-\}
+@
+
+pragma to the header of your file.
+-}
 module GHC.TypeLits.Extra where
 
-import GHC.TypeLits
+import GHC.TypeLits (Nat)
 
--- | Type-level greatest common denominator (GCD)
+-- | Type-level greatest common denominator (GCD).
+--
+-- Note that additional equations are provided by the type-checker plugin solver
+-- "GHC.TypeLits.Extra.Solver".
 type family GCD (x :: Nat) (y :: Nat) :: Nat where
-  GCD 0 x = x
+  GCD 0 x = x -- Additional equations are provided by the custom solver
 
 -- | Type-level equivalent of:
 --
 -- @
 -- clog x y = 'ceiling' ('logBase' x y)
 -- @
+--
+-- Note that additional equations are provided by the type-checker plugin solver
+-- "GHC.TypeLits.Extra.Solver".
 type family CLog (x :: Nat) (y :: Nat) :: Nat where
-  CLog 2 1 = 0
+  CLog 2 1 = 0 -- Additional equations are provided by the custom solver

src/GHC/TypeLits/Extra/Solver.hs

@@ -40,10 +40,17 @@ import TysWiredIn (typeNatKind)
 import GHC.TypeLits.Extra.Solver.Operations
 import GHC.TypeLits.Extra.Solver.Unify
 
--- | To use the plugin, add
+-- | A solver implement as a type-checker plugin for:
+--
+--   * @GHC.TypeLits.Extra.GCD@: a type-level 'gcd'
+--
+--   * @GHC.TypeLits.Extra.CLog@: type-level equivalent of
+--     \"@clog x y = 'ceiling' ('logBase' x y)@\"
+--
+-- To use the plugin, add
 --
 -- @
--- {\-\# OPTIONS_GHC -fplugin GHC.TypeLits.Normalise \#-\}
+-- {\-\# OPTIONS_GHC -fplugin GHC.TypeLits.Extra.Solver \#-\}
 -- @
 --
 -- To the header of your file.