From 7140f96ae3f3e787bbdf6e5018ea3816ebb6613d Mon Sep 17 00:00:00 2001
From: Sridhar Ratnakumar <srid@srid.ca>
Date: Mon, 31 Aug 2020 17:54:58 -0400
Subject: [PATCH] Document IDScheme.hs

---
 .../src/app/Neuron/Zettelkasten/ID/Scheme.hs  | 23 +++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/neuron/src/app/Neuron/Zettelkasten/ID/Scheme.hs b/neuron/src/app/Neuron/Zettelkasten/ID/Scheme.hs
index 7bba67d4a..f8d65eeb9 100644
--- a/neuron/src/app/Neuron/Zettelkasten/ID/Scheme.hs
+++ b/neuron/src/app/Neuron/Zettelkasten/ID/Scheme.hs
@@ -5,7 +5,13 @@
 {-# LANGUAGE TemplateHaskell #-}
 {-# LANGUAGE NoImplicitPrelude #-}
 
-module Neuron.Zettelkasten.ID.Scheme where
+module Neuron.Zettelkasten.ID.Scheme
+  ( nextAvailableZettelID,
+    genVal,
+    IDScheme (..),
+    IDConflict (..),
+  )
+where
 
 import Control.Monad.Except
 import Data.GADT.Compare.TH
@@ -21,9 +27,13 @@ import Relude
 import Text.Megaparsec.Simple
 import Text.Show
 
+-- | The scheme to use when generating new IDs
 data IDScheme a where
+  -- | Legacy date IDs (deprecated)
   IDSchemeDate :: Day -> IDScheme ()
+  -- | Random IDs (default)
   IDSchemeHash :: IDScheme UUID
+  -- | Custom ID (specified by the user)
   IDSchemeCustom :: Text -> IDScheme ()
 
 data IDConflict
@@ -44,7 +54,7 @@ instance Show IDConflict where
     IDConflict_BadCustomID s e ->
       "The custom ID " <> toString s <> " is malformed: " <> toString e
 
--- | Produce a value that is required to run an ID scheme.
+-- | Produce a value that is required ahead to run an ID scheme.
 genVal :: forall a. IDScheme a -> IO a
 genVal = \case
   IDSchemeHash ->
@@ -54,13 +64,18 @@ genVal = \case
   IDSchemeCustom _ ->
     pure ()
 
--- | Create a new zettel ID based on the given scheme without conflicting with
--- the IDs of existing zettels.
+-- | Create a new zettel ID based on the given scheme
+--
+-- This is a pure function, with all impure actions done in @genVal@
+--
+-- Ensures that new ID doesn't conflict with existing zettels.
 nextAvailableZettelID ::
   forall a.
   -- Existing zettels
   Set ZettelID ->
+  -- Seed value for the scheme
   a ->
+  -- Scheme to use when generating an ID
   IDScheme a ->
   Either IDConflict ZettelID
 nextAvailableZettelID zs val = \case