From aaf6ba2f039013b6e9090266911eca4165e0c5b5 Mon Sep 17 00:00:00 2001
From: Tom Willemse <tom@ryuslash.org>
Date: Fri, 4 Nov 2016 18:49:33 +0100
Subject: [PATCH] Add docstrings

---
 circe-serenity.el | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/circe-serenity.el b/circe-serenity.el
index b92a215..de5bf82 100644
--- a/circe-serenity.el
+++ b/circe-serenity.el
@@ -43,9 +43,12 @@
   (setf (alist-get format circe-serenity--formatters-alist) formatter))
 
 (defun circe-serenity--fill-string ()
+  "Create a padded string as long as `circe-serenity-longest-nick'."
   (make-string (+ circe-serenity-longest-nick 3) ?\s))
 
 (defun circe-serenity--update-longest-nick (keywords)
+  "Keep track of the longest nick seen so far.
+KEYWORDS is a plist which should contain a :nick key."
   (let* ((nick (plist-get keywords :nick))
          (len (length nick)))
     (when (> len circe-serenity-longest-nick)
@@ -54,6 +57,9 @@
         (setq-local lui-fill-type (circe-serenity--fill-string))))))
 
 (defun circe-serenity-say-formatter (&rest keywords)
+  "Format a message from a user.
+KEYWORDS should be a plist with at least a :nick and :body.  It
+is passed on to `lui-format'."
   (circe-serenity--update-longest-nick keywords)
   (propertize
    (lui-format (format "{nick:%ds}   {body}" circe-serenity-longest-nick)
@@ -63,6 +69,10 @@
 (circe-serenity--define-formatter 'circe-serenity-say-formatter 'circe-format-self-say)
 
 (defun circe-serenity-action-formatter (&rest keywords)
+  "Format a user's action message.
+KEYWORDS should be plist with at least the keys :nick and :body.
+A key :intro is added to the plist and then passed on to
+`lui-format'."
   (propertize
    (lui-format
     (format "{intro:%ds}   {nick} {body}" circe-serenity-longest-nick)
@@ -71,6 +81,9 @@
 (circe-serenity--define-formatter 'circe-serenity-action-formatter 'circe-format-action)
 
 (defun circe-serenity-server-message-formatter (&rest keywords)
+  "Format a message from the server.
+KEYWORDS should be a plist with at least a :body key.  A key
+:intro is added to the plist and then passed on to `lui-format'."
   (propertize
    (lui-format
     (format "{intro:%ds}   {body}" circe-serenity-longest-nick)
@@ -79,6 +92,10 @@
 (circe-serenity--define-formatter 'circe-serenity-server-message-formatter 'circe-format-server-message)
 
 (defun circe-serenity-server-join-in-channel-formatter (&rest keywords)
+  "Format a message from a user joining a channel.
+KEYWORDS should be a plist with at least a :nick and :channel
+key.  A key :intro is added to the plist and then passed on to
+`lui-format'."
   (propertize
    (lui-format
     (format "{intro:%ds}   {nick} joined {channel}"
@@ -89,6 +106,9 @@
                     'circe-format-server-join-in-channel)
 
 (defun circe-serenity-server-join-formatter (&rest keywords)
+  "Format a message from a user joining the server.
+KEYWORDS should be a plist with at least a :nick key.  A key
+:intro is added to the plist and then passed on to `lui-format'."
   (propertize
    (lui-format
     (format "{intro:%ds}   {nick} logged on"
@@ -98,6 +118,9 @@
 (circe-serenity--define-formatter 'circe-serenity-server-join-formatter 'circe-format-server-join)
 
 (defun circe-serenity-server-quit-formatter (&rest keywords)
+  "Format a message from a user quitting the server.
+KEYWORDS should be a plist with at least a :nick key.  A key
+:intro is added to the plist and then passed on to `lui-format'."
   (propertize
    (lui-format
     (format "{intro:%ds}   {nick} logged off"
@@ -107,6 +130,10 @@
 (circe-serenity--define-formatter 'circe-serenity-server-quit-formatter 'circe-format-server-quit)
 
 (defun circe-serenity-server-quit-channel-formatter (&rest keywords)
+  "Format a message from a user quitting a channel.
+KEYWORDS should be a plist with at least a :nick and :channel
+key.  A key :intro is added to the plist and then passed on to
+`lui-format'."
   (propertize
    (lui-format
     (format "{intro:%ds}   {nick} left {channel}"
@@ -117,6 +144,10 @@
                     'circe-format-server-quit-channel)
 
 (defun circe-serenity-server-part-formatter (&rest keywords)
+  "Format a message from a user parting a channel.
+KEYWORDS should be a plist with at least a :nick and :channel
+key.  A key :intro is added to the plist and then passed on to
+`lui-format'."
   (propertize
    (lui-format
     (format "{intro:%ds}   {nick} parted from {channel}"
@@ -126,6 +157,10 @@
 (circe-serenity--define-formatter 'circe-serenity-server-part-formatter 'circe-format-server-part)
 
 (defun circe-serenity-server-nick-change-formatter (&rest keywords)
+  "Format a message from a user changing their nick.
+KEYWORDS should be a plist with at least a :new-nick and
+:old-nick key.  A key :intro is added to the plist and then
+passed on to `lui-format'."
   (propertize
    (lui-format
     (format "{intro:%ds}   {old-nick} is now know as {new-nick}"
@@ -136,6 +171,10 @@
                     'circe-format-server-nick-change)
 
 (defun circe-serenity-server-topic-formatter (&rest keywords)
+  "Format a message of a topic having changed.
+KEYWORDS should be a plist with at least a :nick and :new-topic
+key.  A key :intro is added to the plist and then passed on to
+`lui-format'."
   (propertize
    (lui-format
     (format "{intro:%ds}   {nick} changed topic to: {new-topic}"
@@ -146,6 +185,7 @@
 
 ;;;###autoload
 (defun enable-circe-serenity ()
+  "Enable Serenity for Circe."
   (interactive)
   (dolist (format-pair circe-serenity--formatters-alist)
     (cl-destructuring-bind (format . formatter) format-pair
@@ -154,6 +194,7 @@
       (set format formatter))))
 
 (defun disable-circe-serenity ()
+  "Disable Serenity for Circe."
   (interactive)
   (dolist (format-pair circe-serenity--formatters-alist)
     (cl-destructuring-bind (format . _) format-pair