Merge pull request #405 from github/document-thy-functions-2

Document thy functions 2

src/Categorizable.hs

@@ -5,12 +5,14 @@ import Term
 import Control.Comonad.Cofree
 import Data.Set
 
+-- | The class of types that have categories.
 class Categorizable a where
   categories :: a -> Set String
 
 instance Categorizable annotation => Categorizable (Term a annotation) where
   categories (annotation :< _) = categories annotation
 
+-- | Test whether the categories from the categorizables intersect.
 comparable :: Categorizable a => a -> a -> Bool
 comparable a b = catsA == catsB || (not . Data.Set.null $ intersection catsA catsB)
   where

src/Diff.hs

@@ -8,20 +8,29 @@ import Term
 import Range
 import Categorizable
 
+-- | An annotated syntax in a diff tree.
 data Annotated a annotation f = Annotated !annotation !(Syntax a f)
   deriving (Functor, Eq, Show, Foldable)
 
+-- | A semantic category.
 type Category = String
+
+-- | An annotation for a source file, including the source range and semantic
+-- | categories.
 data Info = Info { characterRange :: !Range, categories :: !(Set Category) }
   deriving (Eq, Show)
 
 instance Categorizable Info where
   categories = Diff.categories
 
+-- | An annotated series of patches of terms.
 type Diff a annotation = Free (Annotated a (annotation, annotation)) (Patch (Term a annotation))
 
+-- | Sum the result of a transform applied to all the patches in the diff.
 diffSum :: (Patch (Term a annotation) -> Integer) -> Diff a annotation -> Integer
 diffSum patchCost diff = sum $ fmap patchCost diff
 
+-- | The total cost of the diff.
+-- | This is the number of all leaves in all terms in all patches of the diff.
 diffCost :: Diff a annotation -> Integer
 diffCost = diffSum $ patchSum termSize

src/Parser.hs

@@ -9,6 +9,9 @@ import qualified Data.Set as Set
 import Source
 import Data.Text as Text
 
+-- | A function that takes a source file and returns an annotated AST.
+-- | The return is in the IO monad because some of the parsers are written in C
+-- | and aren't pure.
 type Parser = Source Char -> IO (Term Text Info)
 
 -- | Given a source string and a term’s annotation & production/child pairs, construct the term.

src/Patch.hs

@@ -1,20 +1,24 @@
 module Patch where
 
+-- | An operation to replace, insert, or delete an item.
 data Patch a =
   Replace a a
   | Insert a
   | Delete a
   deriving (Functor, Show, Eq)
 
+-- | Return the item from the after side of the patch.
 after :: Patch a -> Maybe a
 after (Replace _ a) = Just a
 after (Insert a) = Just a
 after _ = Nothing
 
+-- | Return the item from the before side of the patch.
 before :: Patch a -> Maybe a
 before (Replace a _) = Just a
 before (Delete a) = Just a
 before _ = Nothing
 
+-- | Calculate the cost of the patch given a function to compute the cost of a item.
 patchSum :: (a -> Integer) -> Patch a -> Integer
 patchSum termCost patch = (maybe 0 termCost $ before patch) + (maybe 0 termCost $ after patch)