GitHub comments -- #77

14 files changed, 54 insertions, 124 deletions

diff --git a/sx-auth.el b/sx-auth.el
index 99344c0..14453ac 100644
--- a/sx-auth.el
+++ b/sx-auth.el
@@ -19,8 +19,6 @@
 
 ;;; Commentary:
 
-;;
-
 ;;; Code:
 
 (require 'sx)
@@ -36,14 +34,12 @@
 (defvar sx-auth-access-token
   nil
   "Your access token.
-
 This is needed to use your account to write questions, make
 comments, and read your inbox.  Do not alter this unless you know
 what you are doing!")
 
 (defun sx-auth-authenticate ()
   "Authenticate this application.
-
 Authentication is required to read your personal data (such as
 notifications) and to write with the API (asking and answering
 questions).
diff --git a/sx-cache.el b/sx-cache.el
index 049e171..9f152e2 100644
--- a/sx-cache.el
+++ b/sx-cache.el
@@ -47,7 +47,6 @@
 
 (defun sx-cache-get (cache &optional form)
   "Return the data within CACHE.
-
 If CACHE does not exist, use `sx-cache-set' to set CACHE to the
 result of evaluating FORM.
 
@@ -64,8 +63,7 @@ CACHE is resolved to a file name by `sx-cache-get-file-name'."
       (sx-cache-set cache (eval form)))))
 
 (defun sx-cache-set (cache data)
-  "Set the content of CACHE to DATA and save changes permanently.
-
+  "Set the content of CACHE to DATA and save.
 DATA will be written as returned by `prin1'.
 
 CACHE is resolved to a file name by `sx-cache-get-file-name'."
@@ -86,10 +84,8 @@ re-initialize the cache."
 
 (defun sx-cache-invalidate-all (&optional save-auth)
   "Invalidate all caches using `sx-cache--invalidate'.
-
-Afterwards reinitialize caches using `sx-initialize'.
-
-If SAVE-AUTH is non-nil, do not clear AUTH cache."
+Afterwards reinitialize caches using `sx-initialize'.  If
+SAVE-AUTH is non-nil, do not clear AUTH cache."
   (let ((caches (let ((default-directory sx-cache-directory))
                   (file-expand-wildcards "*.el"))))
     (when save-auth
diff --git a/sx-encoding.el b/sx-encoding.el
index 8af020e..f683615 100644
--- a/sx-encoding.el
+++ b/sx-encoding.el
@@ -61,7 +61,6 @@
            upsilon "υ" uuml "ü" Uuml "Ü" weierp "℘" Xi "Ξ" xi "ξ" yacute "ý"
            Yacute "Ý" yen "¥" yuml "ÿ" Yuml "Ÿ" Zeta "Ζ" zeta "ζ" zwj "" zwnj "")
   "Plist of HTML entities and their respective glyphs.
-
 See `sx-encoding-decode-entities'."
   :type '(repeat (choice symbol string))
   :group 'sx)
@@ -89,7 +88,6 @@ Return the decoded string."
 
 (defun sx-encoding-normalize-line-endings (string)
   "Normalize the line endings for STRING.
-
 The API returns strings that use Windows-style line endings.
 These are largely useless in an Emacs environment.  Windows uses
 \"\\r\\n\", Unix uses just \"\\n\".  Deleting \"\\r\" is sufficient for
@@ -98,7 +96,6 @@ conversion."
 
 (defun sx-encoding-clean-content (string)
   "Clean STRING for display.
-
 Applies `sx-encoding-normalize-line-endings' and
 `sx-encoding-decode-entities' (in that order) to prepare STRING
 for sane display."
@@ -135,8 +132,7 @@ some cases."
      (t data))))
 
 (defun sx-encoding-gzipped-p (data)
-  "Checks for magic bytes in DATA.
-
+  "Check for magic bytes in DATA.
 Check if the first two bytes of a string in DATA match the magic
 numbers identifying the gzip file format.
 
@@ -145,15 +141,15 @@ See URL `http://www.gzip.org/zlib/rfc-gzip.html'."
   (equal (substring (string-as-unibyte data) 0 2)
          (unibyte-string 31 139)))
 
-(defun sx-encoding-gzipped-buffer-p (filename)
-  "Check if the BUFFER is gzip-compressed.
-
+(defun sx-encoding-gzipped-buffer-p (buffer)
+  "Check if BUFFER is gzip-compressed.
 See `sx-encoding-gzipped-p'."
-  (sx-encoding-gzip-check-magic (buffer-string)))
+  (with-current-buffer buffer
+    (sx-encoding-gzip-check-magic
+     (buffer-string))))
 
 (defun sx-encoding-gzipped-file-p (file)
   "Check if the FILE is gzip-compressed.
-
 See `sx-encoding-gzipped-p'."
   (let ((first-two-bytes (with-temp-buffer
                            (set-buffer-multibyte nil)
diff --git a/sx-favorites.el b/sx-favorites.el
index 3aa96dd..71079fb 100644
--- a/sx-favorites.el
+++ b/sx-favorites.el
@@ -19,8 +19,6 @@
 
 ;;; Commentary:
 
-;;
-
 ;;; Code:
 
 (require 'sx-method)
@@ -39,13 +37,11 @@
 
 (defvar sx-favorites--user-favorite-list nil
   "Alist of questions favorited by the user.
-
 Each element has the form (SITE FAVORITE-LIST).  And each element
 in FAVORITE-LIST is the numerical QUESTION_ID.")
 
 (defun sx-favorites--initialize ()
   "Ensure question-favorites cache is available.
-
 Added as hook to initialization."
   (or   (setq sx-favorites--user-favorite-list
               (sx-cache-get 'question-favorites))
@@ -62,7 +58,6 @@ Added as hook to initialization."
 
 (defun sx-favorites--update-site-favorites (site)
   "Update list of starred QUESTION_IDs for SITE.
-
 Writes list to cache QUESTION-FAVORITES."
   (let* ((favs (sx-favorites--retrieve-favorites site))
          (site-cell (assoc site
diff --git a/sx-filter.el b/sx-filter.el
index 5c878c5..38084b9 100644
--- a/sx-filter.el
+++ b/sx-filter.el
@@ -34,7 +34,6 @@
 (defvar sx--filter-alist
   (sx-cache-get 'filter)
   "An alist of known filters.  See `sx-filter-compile'.
-
 Structure:
 
     (((INCLUDE  EXCLUDE  BASE ) . \"compiled filter \")
@@ -47,7 +46,6 @@ Structure:
 ;;; @TODO allow BASE to be a precompiled filter name
 (defun sx-filter-compile (&optional include exclude base)
   "Compile INCLUDE and EXCLUDE into a filter derived from BASE.
-
 INCLUDE and EXCLUDE must both be lists; BASE should be a string.
 
 Returns the compiled filter as a string."
diff --git a/sx-method.el b/sx-method.el
index 2d8f9d2..8909a2b 100644
--- a/sx-method.el
+++ b/sx-method.el
@@ -34,6 +34,7 @@
 (defun sx-method-call
     (method &optional keyword-arguments filter need-auth use-post)
   "Call METHOD with KEYWORD-ARGUMENTS using FILTER.
+This is a high-level wrapper for `sx-request-make'.
 
 If NEED-AUTH is non-nil, an auth-token is required.  If 'WARN,
 warn the user `(user-error ...)' if they do not have an AUTH
@@ -42,9 +43,7 @@ token set.
 If USE-POST is non-nil, use `POST' rather than `GET' for passing
 arguments.
 
-Return the response content as a complex alist.
-
-See `sx-request-make' and `sx-filter-get-var'."
+Return the response content as a complex alist."
   (sx-request-make method
    (cons (cons 'filter (sx-filter-get-var filter))
          keyword-arguments)
diff --git a/sx-networks.el b/sx-networks.el
index 755d62c..6820e11 100644
--- a/sx-networks.el
+++ b/sx-networks.el
@@ -19,8 +19,6 @@
 
 ;;; Commentary:
 
-;;
-
 ;;; Code:
 
 (require 'sx-method)
@@ -54,7 +52,6 @@
 
 (defun sx-network--get-associated ()
   "Retrieve cached information for network user.
-
 If cache is not available, retrieve current data."
   (or (and (setq sx-network--user-information (sx-cache-get 'network-user)
                  sx-network--user-sites
@@ -63,7 +60,6 @@ If cache is not available, retrieve current data."
 
 (defun sx-network--update ()
   "Update user information.
-
 Sets cache and then uses `sx-network--get-associated' to update
 the variables."
   (sx-cache-set 'network-user
@@ -75,7 +71,6 @@ the variables."
 
 (defun sx-network--initialize ()
   "Ensure network-user cache is available.
-
 Added as hook to initialization."
   ;; Cache was not retrieved, retrieve it.
   (sx-network--get-associated))
@@ -83,7 +78,6 @@ Added as hook to initialization."
 
 (defun sx-network--map-site-url-to-site-api ()
   "Convert `me/associations' to a set of `api_site_parameter's.
-
 `me/associations' does not return `api_site_parameter' so cannot
 be directly used to retrieve content per site.  This creates a
 list of sites the user is active on."
diff --git a/sx-question-list.el b/sx-question-list.el
index cad67a1..9e94536 100644
--- a/sx-question-list.el
+++ b/sx-question-list.el
@@ -161,7 +161,7 @@ Non-interactively, DATA is a question alist."
              (tabulated-list-get-id)
            (user-error "Not in `sx-question-list-mode'"))))
   (sx-question--mark-read data)
-  (sx-question-list-next 1)  
+  (sx-question-list-next 1)
   (when (called-interactively-p 'any)
     (sx-question-list-refresh 'redisplay 'noupdate)))
 
@@ -211,13 +211,11 @@ Non-interactively, DATA is a question alist."
 
 (defvar sx-question-list--current-dataset nil
   "The logical data behind the displayed list of questions.
-
 This dataset contains even questions that are hidden by the user,
 and thus not displayed in the list of questions.")
 
 (defun sx-question-list-refresh (&optional redisplay no-update)
   "Update the list of questions.
-
 If REDISPLAY is non-nil (or if interactive), also call `tabulated-list-print'.
 If the prefix argument NO-UPDATE is nil, query StackExchange for
 a new list before redisplaying."
@@ -248,14 +246,13 @@ a new list before redisplaying."
 
 (defcustom sx-question-list-ago-string " ago"
   "String appended to descriptions of the time since something happened.
-
-Used in the questions list to indicate a question was updated \"4d ago\"."
+Used in the questions list to indicate a question was updated
+\"4d ago\"."
   :type 'string
   :group 'sx-question-list)
 
 (defun sx-question-list--print-info (question-data)
   "Convert `json-read' QUESTION-DATA into tabulated-list format.
-
 See `sx-question-list-refresh'."
   (sx-assoc-let question-data
     (let ((favorite (if (member .question_id
@@ -293,16 +290,14 @@ See `sx-question-list-refresh'."
          (propertize " " 'display "\n")))))))
 
 (defun sx-question-list-view-previous (n)
-  "Move to the previous question and display it.
-
+  "Move cursor up N questions up and display this question.
 Displayed in `sx-question-mode--window', replacing any question
 that may currently be there."
   (interactive "p")
   (sx-question-list-view-next (- n)))
 
 (defun sx-question-list-view-next (n)
-  "Move to the next question and display it.
-
+  "Move cursor down N questions and display this question.
 Displayed in `sx-question-mode--window', replacing any question
 that may currently be there."
   (interactive "p")
@@ -310,22 +305,19 @@ that may currently be there."
   (sx-question-list-display-question))
 
 (defun sx-question-list-next (n)
-  "Move to the next entry.
-
+  "Move cursor down N questions.
 This does not update `sx-question-mode--window'."
   (interactive "p")
   (forward-line n))
 
 (defun sx-question-list-previous (n)
-  "Move to the previous entry.
-
+  "Move cursor up N questions.
 This does not update `sx-question-mode--window'."
   (interactive "p")
   (sx-question-list-next (- n)))
 
 (defun sx-question-list-display-question (&optional data focus)
   "Display question given by DATA.
-
 When DATA is nil, display question under point.  When FOCUS is
 non-nil (the default when called interactively), also focus the
 relevant window."
@@ -364,8 +356,7 @@ relevant window."
 
 (defun sx-question-list-switch-site (site)
   "Switch the current site to SITE and display its questions.
-
-Uses `ido-completing-read' if `ido-mode' is active.  Retrieves
+Uses `ido-completing-read' if variable `ido-mode' is active.  Retrieves
 completions from `sx-site-get-api-tokens'.  Sets
 `sx-question-list--current-site' and then
 `sx-question-list-refresh' with `redisplay'."
@@ -383,7 +374,6 @@ completions from `sx-site-get-api-tokens'.  Sets
 
 (defun list-questions (no-update)
   "Display a list of StackExchange questions.
-
 NO-UPDATE is passed to `sx-question-list-refresh'."
   (interactive "P")
   (sx-initialize)
diff --git a/sx-question-mode.el b/sx-question-mode.el
index 37d50f9..f8a0d1e 100644
--- a/sx-question-mode.el
+++ b/sx-question-mode.el
@@ -51,7 +51,6 @@
 
 (defun sx-question-mode--display (data &optional window)
   "Display question given by DATA on WINDOW.
-
 If WINDOW is nil, use selected one.
 
 Returns the question buffer."
@@ -65,9 +64,7 @@ Returns the question buffer."
 
 (defun sx-question-mode--display-buffer (window)
   "Display and return the buffer used for displaying a question.
-
 Create `sx-question-mode--buffer' if necessary.
-
 If WINDOW is given, use that to display the buffer."
   ;; Create the buffer if necessary.
   (unless (buffer-live-p sx-question-mode--buffer)
@@ -88,7 +85,7 @@ If WINDOW is given, use that to display the buffer."
 ;;;; Faces and Variables
 
 (defvar sx-question-mode--overlays nil
-  "")
+  "Question mode overlays.")
 (make-variable-buffer-local 'sx-question-mode--overlays)
 
 (defface sx-question-mode-header
@@ -150,14 +147,12 @@ If WINDOW is given, use that to display the buffer."
   '((((background dark)) :background "#090909")
     (((background light)) :background "#f4f4f4"))
   "Face used on the question body in the question buffer.
-
 This shouldn't have a foreground, or this will interfere with
 font-locking."
   :group 'sx-question-mode-faces)
 
 (defcustom sx-question-mode-last-edit-format " (edited %s ago by %s)"
   "Format used to describe last edit date in the header.
-
 First \"%s\" is replaced with the date and the second \"%s\" with
 the editor's name."
   :type 'string
@@ -181,7 +176,6 @@ the editor's name."
 
 (defcustom sx-question-mode-comments-format "%s: %s\n"
   "Format used to display comments.
-
 First \"%s\" is replaced with user name.  Second \"%s\" is
 replaced with the comment."
   :type 'string
@@ -197,7 +191,6 @@ replaced with the comment."
 ;;;; Functions
 (defun sx-question-mode--print-question (question)
   "Print a buffer describing QUESTION.
-
 QUESTION must be a data structure returned by `json-read'."
   (setq sx-question-mode--data question)
   ;; Clear the overlays
@@ -213,21 +206,20 @@ QUESTION must be a data structure returned by `json-read'."
 
 (defvar sx-question-mode--section-help-echo
   (format
-   (propertize "%s to hide/display content" 'face 'minibuffer-prompt) 
-   (propertize "RET" 'face 'font-lock-function-name-face)) 
-  "")
+   (propertize "%s to hide/display content" 'face 'minibuffer-prompt)
+   (propertize "RET" 'face 'font-lock-function-name-face))
+  "Help echoed in the minibuffer when point is on a section.")
 
 (defvar sx-question-mode--title-properties
   `(face sx-question-mode-title
          action sx-question-mode-hide-show-section
          help-echo ,sx-question-mode--section-help-echo
          button t
-         follow-link t) 
-  "")
+         follow-link t)
+  "Title properties.")
 
 (defun sx-question-mode--print-section (data)
   "Print a section corresponding to DATA.
-
 DATA can represent a question or an answer."
   ;; This makes `data' accessible through
   ;; `(get-text-property (point) 'sx-question-mode--data-here)'
@@ -303,7 +295,6 @@ DATA can represent a question or an answer."
 
 (defun sx-question-mode--print-comment (comment-data)
   "Print the comment described by alist COMMENT-DATA.
-
 The comment is indented, filled, and then printed according to
 `sx-question-mode-comments-format'."
   (sx-assoc-let comment-data
@@ -321,8 +312,7 @@ The comment is indented, filled, and then printed according to
        3)))))
 
 (defmacro sx-question-mode--wrap-in-overlay (properties &rest body)
-  "Execute BODY and wrap any inserted text in an overlay.
-
+  "Start a scope with overlay PROPERTIES and execute BODY.
 Overlay is pushed on `sx-question-mode--overlays' and given
 PROPERTIES.
 
@@ -339,8 +329,7 @@ Return the result of BODY."
      result))
 
 (defmacro sx-question-mode--wrap-in-text-property (properties &rest body)
-  "Execute BODY and add PROPERTIES to any inserted text.
-
+  "Start a scope with PROPERTIES and execute BODY.
 Return the result of BODY."
   (declare (indent 1)
            (debug t))
@@ -351,7 +340,6 @@ Return the result of BODY."
 
 (defun sx-question-mode--insert-header (&rest args)
   "Insert propertized ARGS.
-
 ARGS is a list of repeating values -- `header', `value', and
 `face'.  `header' is given `sx-question-mode-header' as a face,
 where `value' is given `face' as its face.
@@ -430,14 +418,13 @@ Syntax:
 
 (defun sx-question-mode--propertize-link (text url)
   "Return a link propertized version of string TEXT.
-
 URL is used as 'help-echo and 'url properties."
   (propertize
    text
    ;; Mouse-over
    'help-echo   (format
                  (propertize "URL: %s, %s to visit" 'face 'minibuffer-prompt)
-                 (propertize url 'face 'default) 
+                 (propertize url 'face 'default)
                  (propertize "RET" 'face 'font-lock-function-name-face))
    ;; In case we need it.
    'url         url
@@ -460,7 +447,6 @@ URL is used as 'help-echo and 'url properties."
 
 (defun sx-question-mode-find-reference (id &optional fallback-id)
   "Find url identified by reference ID in current buffer.
-
 If ID is nil, use FALLBACK-ID instead."
   (save-excursion
     (save-match-data
@@ -489,7 +475,6 @@ If ID is nil, use FALLBACK-ID instead."
 ;; for comments).
 (defcustom sx-question-mode-recenter-line 1
   "Screen line to which we recenter after moving between sections.
-
 This is used as an argument to `recenter', only used if the end
 of section is outside the window.
 
@@ -500,7 +485,6 @@ If nil, no recentering is performed."
 
 (defun sx-question-mode-next-section (&optional n)
   "Move down to next section (question or answer) of this buffer.
-
 Prefix argument N moves N sections down or up."
   (interactive "p")
   (let ((count (if n (abs n) 1)))
@@ -523,14 +507,12 @@ Prefix argument N moves N sections down or up."
 
 (defun sx-question-mode-previous-section (&optional n)
   "Move down to previous section (question or answer) of this buffer.
-
-Prefix argument N moves N sections up or down."
+Prefix argument moves N sections up or down."
   (interactive "p")
   (sx-question-mode-next-section (- (or n 1))))
 
 (defun sx-question-mode--goto-property-change (prop &optional direction)
-  "Move forward until the value of text-property sx-question-mode--PROP changes.
-
+  "Move forward to the next change of text-property sx-question-mode--PROP.
 Return the new value of PROP at point.
 
 If DIRECTION is negative, move backwards instead."
@@ -545,9 +527,9 @@ If DIRECTION is negative, move backwards instead."
     (goto-char (funcall func (point) prop nil limit))
     (get-text-property (point) prop)))
 
-;;; Optional argument is for `push-button'.
 (defun sx-question-mode-hide-show-section (&optional _)
-  "Hide or show section under point."
+  "Hide or show section under point.
+Optional argument _ is for `push-button'."
   (interactive)
   (let ((ov (car (or (sx-question-mode--section-overlays-at (point))
                      (sx-question-mode--section-overlays-at
@@ -567,7 +549,6 @@ If DIRECTION is negative, move backwards instead."
 ;;; Major-mode
 (define-derived-mode sx-question-mode markdown-mode "Question"
   "Major mode to display and navigate a question and its answers.
-
 Letters do not insert themselves; instead, they are commands.
 
 \\<sx-question-mode>
@@ -616,7 +597,6 @@ Letters do not insert themselves; instead, they are commands.
 
 (defun sx-question-mode-refresh ()
   "Refresh currently displayed question.
-
 Queries the API for any changes to the question or its answers or
 comments, and redisplays it."
   (interactive)
diff --git a/sx-question.el b/sx-question.el
index cccf525..f6b7beb 100644
--- a/sx-question.el
+++ b/sx-question.el
@@ -43,12 +43,11 @@
      answer.body_markdown
      answer.comments)
     (user.profile_image shallow_user.profile_image))
-  "The filter applied with `sx-question-get-questions' and
-  `sx-question-get-question'.")
+  "The filter applied when retrieving question data.
+See `sx-question-get-questions' and `sx-question-get-question'.")
 
 (defun sx-question-get-questions (site &optional page)
-  "Get the page PAGE of questions from SITE.
-
+  "Get SITE questions.  Return page PAGE (the first if nil).
 Return a list of question.  Each question is an alist of
 properties returned by the API with an added (site SITE)
 property.
@@ -64,7 +63,6 @@ property.
 
 (defun sx-question-get-question (site question-id)
   "Query SITE for a QUESTION-ID and return it.
-
 If QUESTION-ID doesn't exist on SITE, raise an error."
   (let ((res (sx-method-call
               (format "questions/%s" question-id)
@@ -79,7 +77,7 @@ If QUESTION-ID doesn't exist on SITE, raise an error."
 ;;; Question Properties
 
 ;;;; Read/unread
-(defvar sx-question--user-read-list nil 
+(defvar sx-question--user-read-list nil
   "Alist of questions read by the user.
 
 Each element has the form
@@ -92,7 +90,6 @@ where each element in QUESTION-LIST has the form
 
 (defun sx-question--ensure-read-list (site)
   "Ensure `sx-question--user-read-list' has been read from cache.
-
 If no cache exists for it, initialize one with SITE."
   (unless sx-question--user-read-list
     (setq sx-question--user-read-list
@@ -100,7 +97,6 @@ If no cache exists for it, initialize one with SITE."
 
 (defun sx-question--read-p (question)
   "Non-nil if QUESTION has been read since last updated.
-
 See `sx-question--user-read-list'."
   (sx-assoc-let question
     (sx-question--ensure-read-list .site)
@@ -111,7 +107,6 @@ See `sx-question--user-read-list'."
 
 (defun sx-question--mark-read (question)
   "Mark QUESTION as being read until it is updated again.
-
 See `sx-question--user-read-list'."
   (sx-assoc-let question
     (sx-question--ensure-read-list .site)
@@ -136,7 +131,7 @@ See `sx-question--user-read-list'."
 
 
 ;;;; Hidden
-(defvar sx-question--user-hidden-list nil 
+(defvar sx-question--user-hidden-list nil
   "Alist of questions hidden by the user.
 
 Each element has the form
diff --git a/sx-request.el b/sx-request.el
index c49a62d..906785b 100644
--- a/sx-request.el
+++ b/sx-request.el
@@ -20,7 +20,7 @@
 ;;; Commentary:
 
 ;; API requests are handled on three separate tiers:
-;; 
+;;
 ;; `sx-method-call':
 ;;
 ;;    This is the function that should be used most often, since it
@@ -39,7 +39,7 @@
 ;;    The whole solution is built upon `url-retrieve-synchronously'
 ;;    for making the request and `json-read-from-string' for parsing
 ;;    it into a properly symbolic data structure.
-;; 
+;;
 ;; When at all possible, use `sx-method-call'.  There are specialized
 ;; cases for the use of `sx-request-make' outside of sx-method.el, but
 ;; these must be well-documented inline with the code.
@@ -70,7 +70,6 @@
 (defcustom sx-request-unzip-program
   "gunzip"
   "Program used to unzip the response if it is compressed.
-
 This program must accept compressed data on standard input."
   :group 'sx-request
   :type 'string)
@@ -78,13 +77,11 @@ This program must accept compressed data on standard input."
 (defvar sx-request-remaining-api-requests
   nil
   "The number of API requests remaining.
-
 Set by `sx-request-make'.")
 
 (defcustom sx-request-remaining-api-requests-message-threshold
   50
   "Lower bound for printed warnings of API usage limits.
-
 After `sx-request-remaining-api-requests' drops below this
 number, `sx-request-make' will begin printing out the
 number of requests left every time it finishes a call."
@@ -97,10 +94,12 @@ number of requests left every time it finishes a call."
 (defun sx-request-make
     (method &optional args need-auth use-post)
   "Make a request to the API, executing METHOD with ARGS.
-
 You should almost certainly be using `sx-method-call' instead of
 this function.
 
+If NEED-AUTH is non-nil, authentication will be provided.  If
+USE-POST is non-nil, the request will use POST instead of GET.
+
 Returns cleaned response content.
 See (`sx-encoding-clean-content-deep').
 
@@ -176,12 +175,13 @@ the main content of the response is returned."
 (defun sx-request--build-keyword-arguments (alist &optional
 						  kv-sep need-auth)
   "Format ALIST as a key-value list joined with KV-SEP.
-
 If authentication is needed, include it also or error if it is
 not available.
 
+If NEED-AUTH is non-nil, authentication is required.
+
 Build a \"key=value&key=value&...\"-style string with the elements
-of ALIST.  If any value in the alist is `nil', that pair will not
+of ALIST.  If any value in the alist is nil, that pair will not
 be included in the return.  If you wish to pass a notion of
 false, use the symbol `false'.  Each element is processed with
 `sx--thing-as-string'."
diff --git a/sx-site.el b/sx-site.el
index 4e880b1..66d78dc 100644
--- a/sx-site.el
+++ b/sx-site.el
@@ -42,9 +42,10 @@
      related_site.relation)
     nil
     none)
-  "")
+  "Filter for browsing sites.")
 
 (defun sx-site--get-site-list ()
+  "Return all sites with `sx-site-browse-filter'."
   (sx-cache-get
    'site-list
    '(sx-method-call
@@ -54,7 +55,6 @@
 (defcustom sx-site-favorites
   nil
   "List of favorite sites.
-
 Each entry is a string corresponding to a single site's
 api_site_parameter."
   :group 'sx-site)
diff --git a/sx-time.el b/sx-time.el
index 1ce0886..9c4dfaa 100644
--- a/sx-time.el
+++ b/sx-time.el
@@ -51,14 +51,12 @@
 
 (defcustom sx-time-date-format-year "%H:%M %e %b %Y"
   "Format used for dates on a past year.
-
 See also `sx-time-date-format'."
   :type 'string
   :group 'sx-time)
 
 (defcustom sx-time-date-format "%H:%M - %d %b"
   "Format used for dates on this year.
-
 See also `sx-time-date-format-year'."
   :type 'string
   :group 'sx-time)
diff --git a/sx.el b/sx.el
index b1730c5..061c85d 100644
--- a/sx.el
+++ b/sx.el
@@ -49,7 +49,7 @@
 
 (defmacro sx-sorted-insert-skip-first (newelt list &optional predicate)
   "Inserted NEWELT into LIST sorted by PREDICATE.
-This is designed for the (site id id ...) lists. So the first car
+This is designed for the (site id id ...) lists.  So the first car
 is intentionally skipped."
   `(let ((tail ,list)
          (x ,newelt))
@@ -61,7 +61,8 @@ is intentionally skipped."
      (setcdr tail (cons x (cdr tail)))))
 
 (defun sx-message (format-string &rest args)
-  "Display a message."
+  "Display FORMAT-STRING as a message with ARGS.
+See `format'."
   (message "[stack] %s" (apply #'format format-string args)))
 
 (defun sx-message-help-echo ()
@@ -71,7 +72,6 @@ is intentionally skipped."
 
 (defun sx--thing-as-string (thing &optional sequence-sep)
   "Return a string representation of THING.
-
 If THING is already a string, just return it.
 
 Optional argument SEQUENCE-SEP is the separator applied between
@@ -98,7 +98,7 @@ For example:
       (prop4 . t))
     '(prop1 (prop3 test2)))
 
-would yeild
+would yield
 
   ((prop1 . value1)
    (prop3
@@ -132,8 +132,7 @@ would yeild
 ;;; Interpreting request data
 (defun sx--deep-dot-search (data)
   "Find symbols somewhere inside DATA which start with a `.'.
-
-Returns a list where each element is a cons cell. The car is the
+Returns a list where each element is a cons cell.  The car is the
 symbol, the cdr is the symbol without the `.'."
   (cond
    ((symbolp data)
@@ -148,9 +147,8 @@ symbol, the cdr is the symbol without the `.'."
        (remove nil (mapcar #'sx--deep-dot-search data))))))
 
 (defmacro sx-assoc-let (alist &rest body)
-  "Execute BODY with dotted symbols let-bound to their values in ALIST.
-
-Dotted symbol is any symbol starting with a `.'. Only those
+  "Use dotted symbols let-bound to their values in ALIST and execute BODY.
+Dotted symbol is any symbol starting with a `.'.  Only those
 present in BODY are letbound, which leads to optimal performance.
 
 For instance, the following code
@@ -172,20 +170,17 @@ is equivalent to
 
 (defcustom sx-init-hook nil
   "Hook run when stack-mode initializes.
-
 Run after `sx-init--internal-hook'."
   :group 'sx
   :type 'hook)
 
 (defvar sx-init--internal-hook nil
   "Hook run when stack-mode initializes.
-
 This is used internally to set initial values for variables such
 as filters.")
 
 (defun sx--< (property x y &optional predicate)
   "Non-nil if PROPERTY attribute of alist X is less than that of Y.
-
 With optional argument PREDICATE, use it instead of `<'."
   (funcall (or predicate #'<)
            (cdr (assoc property x))
@@ -193,7 +188,6 @@ With optional argument PREDICATE, use it instead of `<'."
 
 (defmacro sx-init-variable (variable value &optional setter)
   "Set VARIABLE to VALUE using SETTER.
-
 SETTER should be a function of two arguments.  If SETTER is nil,
 `set' is used."
   (eval
@@ -209,7 +203,6 @@ If it has, holds the time at which initialization happened.")
 
 (defun sx-initialize (&optional force)
   "Run initialization hooks if they haven't been run yet.
-
 These are `sx-init--internal-hook' and `sx-init-hook'.
 
 If FORCE is non-nil, run them even if they've already been run."