From f346b9cb5804819edf9d186bcb2939be08298ac3 Mon Sep 17 00:00:00 2001
From: dece <shgck@pistache.land>
Date: Sun, 1 Nov 2020 19:29:51 +0100
Subject: [PATCH] bot: add docs

---
 README.md              | 1 +
 edmond/bot.py          | 7 +++++++
 edmond/plugin.py       | 1 +
 edmond/plugins/mood.py | 6 ++++++
 4 files changed, 15 insertions(+)

diff --git a/README.md b/README.md
index e741025..05edbbf 100644
--- a/README.md
+++ b/README.md
@@ -52,3 +52,4 @@ Missing features
     - [ ] "???"
 - [ ] Simple word mappings for fun
 - [ ] Lyrics
+- [ ] Phonétique
diff --git a/edmond/bot.py b/edmond/bot.py
index 1455f8a..d2b2821 100644
--- a/edmond/bot.py
+++ b/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]
diff --git a/edmond/plugin.py b/edmond/plugin.py
index 391dd0a..1ef93cb 100644
--- a/edmond/plugin.py
+++ b/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)
 
diff --git a/edmond/plugins/mood.py b/edmond/plugins/mood.py
index a90587c..9ea4b40 100644
--- a/edmond/plugins/mood.py
+++ b/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"]