From 0e0596765eb8d6ebbaad3a12f2f8d6a96f66bd3a Mon Sep 17 00:00:00 2001
From: Joscha <joscha@plugh.de>
Date: Wed, 8 Apr 2020 21:53:16 +0000
Subject: [PATCH] Add botrulez documentation

---
 src/Haboli/Euphoria/Botrulez.hs | 16 ++++++++++++++++
 src/Haboli/Euphoria/Command.hs  | 10 +++++++---
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/src/Haboli/Euphoria/Botrulez.hs b/src/Haboli/Euphoria/Botrulez.hs
index 09deb05..3f24d0d 100644
--- a/src/Haboli/Euphoria/Botrulez.hs
+++ b/src/Haboli/Euphoria/Botrulez.hs
@@ -1,5 +1,9 @@
 {-# LANGUAGE OverloadedStrings #-}
 
+-- | This module implements a few commands defined in the
+-- [botrulez](https://github.com/jedevc/botrulez). If you need more advanced
+-- behaviour, it should be pretty easy to reimplement the commands as necessary.
+
 module Haboli.Euphoria.Botrulez
   ( botrulezPingGeneral
   , botrulezPingSpecific
@@ -20,22 +24,32 @@ import           Haboli.Euphoria.Command
 import           Haboli.Euphoria.Command.Simple
 import           Haboli.Euphoria.Util
 
+-- | @'botrulezPingGeneral'@ replies to commands of the form @!ping@ with
+-- @Pong!@.
 botrulezPingGeneral :: Command e
 botrulezPingGeneral = cmdGeneral "ping" $ \msg ->
   void $ reply msg "Pong!"
 
+-- | @'botrulezPingSpecific' nick@ replies to commands of the form @!ping
+-- \@nick@ with @Pong!@.
 botrulezPingSpecific :: T.Text -> Command e
 botrulezPingSpecific name = cmdSpecific "ping" name $ \msg ->
   void $ reply msg "Pong!"
 
+-- | @'botrulezHelpGeneral' helpText@ replies to commands of the form @!help@
+-- with @helpText@.
 botrulezHelpGeneral :: T.Text -> Command e
 botrulezHelpGeneral help = cmdGeneral "help" $ \msg ->
   void $ reply msg help
 
+-- | @'botrulezHelpSpecific' nick helpText@ replies to commands of the form
+-- @!help \@nick@ with @helpText@.
 botrulezHelpSpecific :: T.Text -> T.Text -> Command e
 botrulezHelpSpecific name help = cmdSpecific "help" name $ \msg ->
   void $ reply msg help
 
+-- | @'botrulezUptimeSpecific' nick startTime@ replies to commands of the form
+-- @!uptime \@nick@ with the time since @startTime@.
 botrulezUptimeSpecific :: T.Text -> UTCTime -> Command e
 botrulezUptimeSpecific name since = cmdSpecific "uptime" name $ \msg -> do
   now <- liftIO getCurrentTime
@@ -48,6 +62,8 @@ botrulezUptimeSpecific name since = cmdSpecific "uptime" name $ \msg -> do
     , ")"
     ]
 
+-- | @'botrulezKillSpecific' nick@ replies to commands of the form @!kill
+-- \@nick@ with @/me dies@. It then throws an exception.
 botrulezKillSpecific :: T.Text -> Command T.Text
 botrulezKillSpecific name = cmdSpecific "kill" name $ \msg -> do
   void $ reply msg "/me dies"
diff --git a/src/Haboli/Euphoria/Command.hs b/src/Haboli/Euphoria/Command.hs
index 33685d6..0ebeb50 100644
--- a/src/Haboli/Euphoria/Command.hs
+++ b/src/Haboli/Euphoria/Command.hs
@@ -25,13 +25,17 @@ runCommands (c:cs) msg = do
     then pure True
     else runCommands cs msg
 
--- | Run a list of 'Command's on all 'EventSend's. Passes through all events
--- unmodified.
+-- | @'respondingToCommands' getEvent getCommands@ runs a list of 'Command's on
+-- all 'EventSend's. It passes through all events unmodified.
+--
+-- The @getEvent@ action is used to obtain the next 'Event'. The @getCommands@
+-- action is used to obtain the currently available commands. @getCommands@ is
+-- called directly after a new 'Event' becomes available through @getEvent@.
 --
 -- This utility function is meant to be wrapped directly or indirectly around
 -- 'nextEvent':
 --
--- > event <- respondingToCommands commands nextEvent
+-- > event <- respondingToCommands nextEvent commands
 respondingToCommands :: Client e Event -> Client e [Command e] -> Client e Event
 respondingToCommands getEvent getCommands = do
   event <- getEvent