Tidy: Docstrings, comment

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)

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

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

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

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))