Merge pull request #106 from statebox/105/doc

Add doc comments for the most important types. #105

README.md

@@ -22,6 +22,10 @@ Install:
 
 `stack install`
 
+Generate docs:
+
+`stack haddock aql`
+
 ### Cabal
 
 Generate `.cabal` file:

src/Language/Instance.hs

@@ -275,6 +275,7 @@ instance (Show var, Show ty, Show sym, Show en, Show fk, Show att, Show gen, Sho
     "generators\n\t" ++ showCtx' ens' ++ "\n" ++
     "equations\n\t" ++ intercalate "\n\t" (Set.map show eqs') ++ "}"
 
+-- | Instance kinds can be thought of as the data that "fills" the 'Schema'.
 data Instance var ty sym en fk att gen sk x y
   = Instance
   { schema  :: Schema       var  ty sym en fk att
@@ -458,8 +459,10 @@ assembleSks col ens' = unionWith Set.union sks' $ fromListAccum gens'
 
 type Carrier en fk gen = Term Void Void Void en fk Void gen Void
 
--- | T means type. This can be either a labeled null (`sk`) or... a proper value
--- | This type allows us to define e.g. a custom Show instance.
+
+-- | These are the generating labelled nulls for the type 'Algebra' of the associated 'Instance'.
+--   It can be either a labeled null ('Sk') or a proper value.
+--   This newtype allows us to define e.g. a custom 'Show' instance.
 newtype TalgGen en fk att gen sk = MkTalgGen (Either sk (Carrier en fk gen, att))
 
 instance (Show en, Show fk, Show att, Show gen, Show sk) => Show (TalgGen en fk att gen sk) where

src/Language/Term.hs

@@ -98,14 +98,23 @@ simplify eqs = case find eqs of
                  in Just $ (eqs3,(toRemove, replacer))
 
 
-
-
 data Term var ty sym en fk att gen sk
+  -- | Variable.
   = Var var
+
+  -- | Type side function/constant symbol.
   | Sym sym  [Term var ty sym en fk att gen sk]
+
+  -- | Foreign key.
   | Fk  fk   (Term var ty sym en fk att gen sk)
+
+  -- | Attribute.
   | Att att  (Term var ty sym en fk att gen sk)
+
+  -- | Generator.
   | Gen gen
+
+  -- | Skolem term or labelled null; like a generator for a type rather than an entity.
   | Sk  sk
 
 data Head ty sym en fk att gen sk =

src/Language/Transform.hs

@@ -150,6 +150,7 @@ transToMor (Transform src' dst' gens' sks') =
     fks0  = mapWithKey  (\fk  _ -> Fk  fk (Var ())) (S.fks  $ I.schema src')
     atts0 = mapWithKey  (\fk  _ -> Att fk (Var ())) (S.atts $ I.schema src')
 
+-- | Map from one 'Instance' to another of the same 'Schema'.
 data Transform var ty sym en fk att gen sk x y gen' sk' x' y'
   = Transform
   { srcT :: Instance var ty sym en fk att gen sk x y

src/Language/Typeside.hs

@@ -34,7 +34,7 @@ fromList' ((k,v):l) = do l' <- fromList' l
                          else pure $ Map.insert k v l'
 fromList' [] = return Map.empty
 
-
+-- | A user-defined kind for customisation of data types.
 data Typeside var ty sym
   = Typeside
   { tys  :: Set ty