diff --git a/src/main.zig b/src/main.zig
index c41ad19..0caba3b 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -49,6 +49,16 @@ pub const Adapter = struct {
     callbackFn: *const fn (*anyopaque, zircon.Message) ?zircon.Message,
 };
 
+/// BotAdapter is the closure that we register in zircon as the
+/// message callback.
+///
+/// Whenever a message is received by the zircon client it will invoke
+/// BotAdapter.callback (through some indirection) with the received
+/// message.
+///
+/// The main responsibility of BotAdapter is to serve as the
+/// translation layer between our own internal types and the zircon
+/// IRC types.
 pub const BotAdapter = struct {
     bot: Bot,
     allocator: std.mem.Allocator,
@@ -64,6 +74,14 @@ pub const BotAdapter = struct {
         self.bot.deinit();
     }
 
+    /// callback gets called for every message that we receive.
+    ///
+    /// This is where we can extend the bot to support more types of
+    /// messages if needed.
+    ///
+    /// See
+    /// - https://modern.ircdocs.horse/, for what kinds of messages exists in the IRC protocol documentation,
+    /// - https://github.com/Jassob/zircon/blob/main/src/message.zig, for zircon documentation.
     pub fn callback(self: *BotAdapter, message: zircon.Message) ?zircon.Message {
         switch (message) {
             .PRIVMSG => |msg| {
@@ -97,6 +115,7 @@ pub const BotAdapter = struct {
         }
     }
 
+    /// report errors as private message to admin channel.
     fn reportError(err: Error) zircon.Message {
         const err_msg = switch (err) {
             Error.NoMessage => "no matching message",