bot: add docs

README.md

@@ -52,3 +52,4 @@ Missing features
     - [ ] "???"
 - [ ] Simple word mappings for fun
 - [ ] Lyrics
+- [ ] Phonétique

edmond/bot.py

@@ -24,12 +24,14 @@ class Bot(irc.client.SimpleIRCClient, Logger):
 
     @property
     def nick(self):
+        """Nickname validated by the server, or the configured nick."""
         if self.connection.is_connected():
             return self.connection.get_nickname()
         return self.config["nick"]
 
     @property
     def names(self):
+        """Collection of names the bot should identify with."""
         return (self.nick, *self.config["alternative_nicks"])
 
     @property
@@ -62,24 +64,28 @@ class Bot(irc.client.SimpleIRCClient, Logger):
             self.log_e(f"Could not save storage file: {exc}")
 
     def on_welcome(self, connection, event):
+        """Handle a successful connection to a server."""
         self.log_i(f"Connected to server {event.source}.")
         self.run_plugin_callbacks(event)
         for channel in self.config["channels"]:
             connection.join(channel)
 
     def on_join(self, connection, event):
+        """Handle someone, possibly the bot, joining a channel."""
         if event.source.nick == self.nick:
             self.log_i(f"Joined {event.target}.")
             self.channels.append(event.target)
         self.run_plugin_callbacks(event)
 
     def on_part(self, connection, event):
+        """Handle someone, possibly the bot, leaving a channel."""
         if event.source.nick == self.nick:
             self.log_i(f"Left {event.target} (args: {event.arguments[0]}).")
             self.channels.remove(event.target)
         self.run_plugin_callbacks(event)
 
     def on_pubmsg(self, connection, event):
+        """Handle a message received in a channel."""
         channel = event.target
         nick = NickMask(event.source).nick
         message = event.arguments[0]
@@ -87,6 +93,7 @@ class Bot(irc.client.SimpleIRCClient, Logger):
         self.run_plugin_callbacks(event)
 
     def on_privmsg(self, connection, event):
+        """Handle a message received privately."""
         nick = NickMask(event.source).nick
         target = event.target
         message = event.arguments[0]

edmond/plugin.py

@@ -81,6 +81,7 @@ class Plugin:
             self.bot.storage[self.name][key].append(value)
 
     def remove_storage_list_value(self, key, value):
+        """Remove a value from a persistent storage list."""
         if self.name in self.bot.storage and key in self.bot.storage[self.name]:
             self.bot.storage[self.name][key].remove(value)
 

edmond/plugins/mood.py

@@ -10,6 +10,12 @@ class Mood(Enum):
 
 
 class MoodPlugin(Plugin):
+    """Handle the mood of the bot.
+
+    This plugin exposes the runtime value `mood` (Mood) which can be
+    used to act differently upon some actions according to the bot
+    current mood.
+    """
 
     REQUIRED_CONFIGS = ["questions", "greetings", "answer"]