Add/fix some documentation

Author: Brian Jones

backend/src/DataAccess/Todo.hs

@@ -22,6 +22,13 @@ toTodoR t =
           (M.TodoDesc $ todoDesc t)
           (toEnum $ todoStatus t)
 
+-- While not "lawful" typeclasses, we take advantage of the abstraction
+-- so that we can write an intermediate layer between our Domain and
+-- actual datasource (in this particular case a Database layer).
+--
+-- This then allows us to test the Domain logic using the same typeclass
+-- but in some alternative Monad, like Identity or State.
+
 class Monad m => TodoDAM m where
   getTodos :: HasCallStack => m [M.TodoR]
   getTodo :: HasCallStack => M.TodoId -> m (Maybe M.TodoR)

backend/src/Errors.hs

@@ -9,6 +9,9 @@ import Servant
 import Types
 --------------------------------------------------------------------------------
 
+-- Our top level handler captures any errors that get generated and properly
+-- converts them into an ErrorJSON, logs somewhere, and returns the right
+-- HTTP error code.
 handleError :: AppContext -> IO (Either AppError a) -> Handler a
 handleError ctx f = Handler . ExceptT $ convert ctx f
 

backend/src/Routes.hs

@@ -12,7 +12,7 @@ import Models.Todo
 -- In order to get proper route type safety and avoid spelling mistakes like
 -- "user" vs "uesr" in urls we create type synonyms which end up as a Symbol
 type ApiTerm      = "api"
-type Version1Term = "v2"
+type Version1Term = "v1"
 
 -- The top level composition of all of our routes appended together
 type Routes =
@@ -36,21 +36,24 @@ type RoutesTodo =
 type TodoListTerm = "todos"
 type TodoTerm     = "todo"
 
+-- GET /api/v1/todos
 type GetTodos =
   TodoListTerm :>
   Get '[JSON] [TodoR]
 
--- GET /api/v2/todo/{id}
+-- GET /api/v1/todo/{id}
 type GetTodo =
   TodoTerm :>
   Capture "todo_id" TodoId :>
   Get '[JSON] TodoR
 
+-- POST /api/v1/todo
 type CreateTodo =
   TodoTerm :>
   ReqBody '[JSON] TodoC :>
   Post '[JSON] TodoR
 
+-- PUT /api/v1/todo
 type UpdateTodo =
   TodoTerm :>
   ReqBody '[JSON] TodoU :>