From eaab256ccaca66780b4b2b8da06f63551b661fd6 Mon Sep 17 00:00:00 2001
From: Joscha <brummer@migejolise.de>
Date: Mon, 10 Sep 2018 22:17:53 +0000
Subject: [PATCH] Add documentation

---
 src/TaskMachine/Todotxt/Dates.hs    |  1 -
 src/TaskMachine/Todotxt/Priority.hs | 17 ++++++++++++++++-
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/src/TaskMachine/Todotxt/Dates.hs b/src/TaskMachine/Todotxt/Dates.hs
index e39d7bd..f3e7de4 100644
--- a/src/TaskMachine/Todotxt/Dates.hs
+++ b/src/TaskMachine/Todotxt/Dates.hs
@@ -1,6 +1,5 @@
 -- | Read, parse and write files in the <https://github.com/todotxt/todo.txt todo.txt> format.
 
-
 module TaskMachine.Todotxt.Dates
   ( Dates()
   , showDates
diff --git a/src/TaskMachine/Todotxt/Priority.hs b/src/TaskMachine/Todotxt/Priority.hs
index cd72b33..5ccdd80 100644
--- a/src/TaskMachine/Todotxt/Priority.hs
+++ b/src/TaskMachine/Todotxt/Priority.hs
@@ -1,12 +1,12 @@
 -- | Read, parse and write files in the <https://github.com/todotxt/todo.txt todo.txt> format.
 
-
 module TaskMachine.Todotxt.Priority
   ( Priority()
   , priorityToChar
   , charToPriority
   , showPriority
   -- * Parsing
+  , priorityChar
   , priority
   ) where
 
@@ -20,6 +20,14 @@ import           Text.Megaparsec
 import           Text.Megaparsec.Char
 import           Text.Megaparsec.Error
 
+-- | A task's priority.
+--
+-- Priorities are labeled using uppercase A to Z,
+-- with priority A being the most important priority.
+-- In the 'Priority' type, priority A is the smallest priority.
+--
+-- Tasks should be sorted from smallest to largest (i. e. least important) priority.
+-- Tasks without priority should appear after tasks with priority.
 data Priority
   = PrioA | PrioB | PrioC | PrioD | PrioE | PrioF | PrioG
   | PrioH | PrioI | PrioJ | PrioK | PrioL | PrioM | PrioN
@@ -27,9 +35,12 @@ data Priority
   | PrioV | PrioW | PrioX | PrioY | PrioZ
   deriving (Bounded, Enum, Eq, Show, Ord)
 
+-- | Convert a priority to its corresponding character of the alphabet
 priorityToChar :: Priority -> Char
 priorityToChar p = toEnum (fromEnum 'A' + fromEnum p)
 
+-- | Convert a character of the alphabet (uppercase A to Z)
+-- to its corresponding priority
 charToPriority :: Char -> Maybe Priority
 charToPriority c
   | min_value <= value && value <= max_value = Just $ toEnum value
@@ -39,6 +50,8 @@ charToPriority c
     min_value = fromEnum (minBound :: Priority)
     max_value = fromEnum (maxBound :: Priority)
 
+-- | Convert a 'Priority' to a string representation that can be used inside a todo.txt task
+-- and parsed by 'priority'
 showPriority :: Priority -> String
 showPriority p = '(' : priorityToChar p : ")"
 
@@ -46,6 +59,7 @@ showPriority p = '(' : priorityToChar p : ")"
 
 type Parser = Parsec Void String
 
+-- | Parse a priority character (see 'priorityToChar') and return the corresponding priority
 priorityChar :: Parser Priority
 priorityChar = do
   c <- anyChar
@@ -53,5 +67,6 @@ priorityChar = do
     Just p -> pure p
     Nothing -> failure (Just $ Tokens $ c :| []) (Set.singleton $ Label $ 'p' :| "riority character")
 
+-- | Parse a priority of the format @(*)@ where @*@ is a letter of the alphabet (uppercase A to Z)
 priority :: Parser Priority
 priority = char '(' *> priorityChar <* char ')'