From 5350a2e44cfa1b8dd8dc882cfc4e965efc39a59d Mon Sep 17 00:00:00 2001
From: Mark Veidemanis <m@zm.is>
Date: Mon, 27 Dec 2021 21:19:58 +0000
Subject: [PATCH] Document IRC code

---
 handler/irc.py | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/handler/irc.py b/handler/irc.py
index 38ffc37..18bf88f 100644
--- a/handler/irc.py
+++ b/handler/irc.py
@@ -37,6 +37,10 @@ class IRCBot(irc.IRCClient):
     def parse(self, user, host, channel, msg):
         """
         Simple handler for IRC commands.
+        :param user: full user string with host
+        :param host: user's hostname
+        :param channel: channel the message was received on
+        :param msg: the message
         """
         spl = msg.split()
         # nick = user.split("!")[0]
@@ -101,6 +105,7 @@ class IRCBot(irc.IRCClient):
         Called when we have joined a channel.
         Setup the Agora LoopingCall to get trades.
         This is here to ensure the IRC client is initialised enough to send the trades.
+        :param channel: channel we joined
         """
         self.agora.setup_loop()
         self.log.info("Joined channel %s" % (channel))
@@ -109,6 +114,9 @@ class IRCBot(irc.IRCClient):
         """
         Called on received PRIVMSGs.
         Pass through identified commands to the parse function.
+        :param user: full user string with host
+        :param channel: channel the message was received on
+        :param msg: the message
         """
         nick = user.split("!")[0]
 
@@ -126,14 +134,17 @@ class IRCBot(irc.IRCClient):
                 if msg.split()[0] != "!":
                     self.parse(user, host, channel, msg[1:])
 
-    def noticed(self, user, channel, message):
+    def noticed(self, user, channel, msg):
         """
         Called on received NOTICEs.
+        :param user: full user string with host
+        :param channel: channel the notice was received on
+        :param msg: the message
         """
         nick = user.split("!")[0]
         if channel == self.nickname:
             channel = nick
-        # self.log.info("[%s] %s: %s" % (channel, user, message))
+        # self.log.info("[%s] %s: %s" % (channel, user, msg))
 
 
 class IRCBotFactory(protocol.ClientFactory):
@@ -157,6 +168,8 @@ class IRCBotFactory(protocol.ClientFactory):
     def clientConnectionLost(self, connector, reason):
         """
         Called when connection to IRC server lost. Reconnect.
+        :param connector: connector object
+        :param reason: reason connection lost
         """
         self.log.error("Lost connection (%s), reconnecting" % (reason))
         connector.connect()
@@ -164,13 +177,17 @@ class IRCBotFactory(protocol.ClientFactory):
     def clientConnectionFailed(self, connector, reason):
         """
         Called when connection to IRC server failed. Reconnect.
+        :param connector: connector object
+        :param reason: reason connection failed
         """
         self.log.error("Could not connect: %s" % (reason))
         connector.connect()
 
 
 def bot():
+    # Load the certificates
     context = ssl.DefaultOpenSSLContextFactory(settings.IRC.Cert, settings.IRC.Cert)
+    # Define the factory instance
     factory = IRCBotFactory()
     reactor.connectSSL(settings.IRC.Host, int(settings.IRC.Port), factory, context)
     return factory