From d1fceb149eb555e11e57f175b8226a5482d2a080 Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Thu, 1 Sep 2022 23:10:28 -0500
Subject: [PATCH] Tidy: Docstrings, comment

---
 ement-api.el    | 18 ++++++++++++++++--
 ement-lib.el    |  5 ++++-
 ement-notify.el |  2 +-
 ement-room.el   |  5 +++--
 ement-taxy.el   |  4 ++--
 5 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/ement-api.el b/ement-api.el
index 1bf5029..56c19f1 100644
--- a/ement-api.el
+++ b/ement-api.el
@@ -71,8 +71,22 @@
                              ;; can get slow and respond a minute or two later.
                              (connect-timeout 10) (timeout 60)
                              (version "r0"))
-  "FIXME: Docstring."
-  ;; TODO: Remind users to json-encode data when needed.
+  "Make API request on SESSION to ENDPOINT.
+The request automatically uses SESSION's server, URI prefix, and
+access token.
+
+These keyword arguments are passed to `plz', which see: THEN,
+DATA (passed as BODY), QUEUE (passed to `plz-queue', which see),
+DATA-TYPE (passed as BODY-TYPE), ELSE, METHOD,
+JSON-READ-FN (passed as AS), CONNECT-TIMEOUT, TIMEOUT.
+
+Other arguments include PARAMS (used as the URL's query
+parameters), ENDPOINT-CATEGORY (added to the endpoint URL), and
+VERSION (added to the endpoint URL).
+
+Note that most Matrix requests expect JSON-encoded data, so
+usually the DATA argument should be passed through
+`json-encode'."
   (declare (indent defun))
   (pcase-let* (((cl-struct ement-session server token) session)
                ((cl-struct ement-server uri-prefix) server)
diff --git a/ement-lib.el b/ement-lib.el
index 13f417a..78a886b 100644
--- a/ement-lib.el
+++ b/ement-lib.el
@@ -416,7 +416,10 @@ USER is an `ement-user' struct."
 
 (cl-defun ement--prism-color (string &key (contrast-with (face-background 'default nil 'default)))
   "Return a computed color for STRING.
-Useful for user messages, generated room avatars, etc."
+The color is adjusted to have sufficient contrast with the color
+CONTRAST-WITH (by default, the default face's background).  The
+computed color is useful for user messages, generated room
+avatars, etc."
   ;; TODO: Use this instead of `ement-room--user-color'.  (Same algorithm ,just takes a
   ;; string as argument.)
   ;; TODO: Try using HSV somehow so we could avoid having so many strings return a
diff --git a/ement-notify.el b/ement-notify.el
index cac68b3..549aa04 100644
--- a/ement-notify.el
+++ b/ement-notify.el
@@ -222,7 +222,7 @@ anything if session hasn't finished initial sync."
               bookmark-make-record-function #'ement-notify-bookmark-make-record))
 
 (cl-defun ement-notify--log-to-buffer (event room session &key (buffer-name "*Ement Notifications*"))
-  "Log EVENT in ROOM to \"*Ement Notifications*\" buffer."
+  "Log EVENT in ROOM on SESSION to \"*Ement Notifications*\" buffer."
   (with-demoted-errors "ement-notify--log-to-buffer: %S"
     ;; HACK: We only log "m.room.message" events for now.  This shouldn't be necessary
     ;; since we have `ement-notify--event-message-p' in `ement-notify-predicates', but
diff --git a/ement-room.el b/ement-room.el
index d22150a..e82bcd5 100644
--- a/ement-room.el
+++ b/ement-room.el
@@ -1014,7 +1014,8 @@ when switching themes or adjusting `ement-prism' options."
   "Browse URL, using Ement for matrix.to URLs when possible.
 Otherwise, fall back to `browse-url'.  When called outside of an
 `ement-room' buffer, the variable `ement-session' must be bound
-to the session in which to look for URL's room and event."
+to the session in which to look for URL's room and event.  ARGS
+are passed to `browse-url'."
   (interactive)
   (when (string-match ement-room-matrix.to-url-regexp url)
     (let ((room-id (when (string-prefix-p "!" (match-string 1 url))
@@ -2682,7 +2683,7 @@ the first and last nodes in the buffer, respectively."
 (cl-defun ement-room--insert-sender-headers
     (ewoc &optional (start-node (ewoc-nth ewoc 0)) (end-node (ewoc-nth ewoc -1)))
   ;; TODO: Use this in appropriate places.
-  "Insert sender headers into current buffer's `ement-ewoc'.
+  "Insert sender headers into EWOC.
 Inserts headers between START-NODE and END-NODE, which default to
 the first and last nodes in the buffer, respectively."
   (cl-labels ((read-marker-p
diff --git a/ement-taxy.el b/ement-taxy.el
index 8616a67..f45a919 100644
--- a/ement-taxy.el
+++ b/ement-taxy.el
@@ -122,7 +122,7 @@
                                  ;; Room is a specified space.
                                  (or name (concat "Space: " (ement-room-display-name room)))
                                  ))
-                        ;; ID not specified. 
+                        ;; ID not specified.
                         (pcase (length parents)
                           (0 nil)
                           (1
@@ -538,7 +538,7 @@ left."
   (ement-taxy-room-list :display-buffer-action '(display-buffer-no-window (allow-no-window . t))))
 
 (defun ement-taxy-mouse-1 (event)
-  "Call `ement-taxy-RET' at point."
+  "Call `ement-taxy-RET' at EVENT."
   (interactive "e")
   (mouse-set-point event)
   (call-interactively #'ement-taxy-RET))