Documentation -- part three

Source code is documented to the best of my knowledge and understanding.

6 files changed, 101 insertions, 42 deletions

diff --git a/sx-question-mode.el b/sx-question-mode.el
index e436b40..d971a49 100644
--- a/sx-question-mode.el
+++ b/sx-question-mode.el
@@ -150,14 +150,16 @@ 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.
-Shouldn't have a foreground, or this will interfere with
+
+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."
+
+First \"%s\" is replaced with the date and the second \"%s\" with
+the editor's name."
   :type 'string
   :group 'sx-question-mode)
 
@@ -179,8 +181,9 @@ 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."
+
+First \"%s\" is replaced with user name.  Second \"%s\" is
+replaced with the comment."
   :type 'string
   :group 'sx-question-mode)
 
@@ -194,6 +197,7 @@ Second \"%s\" is 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'."
   ;; Clear the overlays
   (mapc #'delete-overlay sx-question-mode--overlays)
@@ -220,10 +224,11 @@ QUESTION must be a data structure returned by `json-read'."
          follow-link t) 
   "")
 
-(defun sx-question-mode--print-section (data)
-  "Print a section corresponding to DATA.
-DATA can represent a question or an answer."
-  (sx-assoc-let data
+(defun sx-question-mode--print-section (question-data)
+  "Print a section corresponding to QUESTION-DATA.
+
+QUESTION-DATA can represent a question or an answer."
+  (sx-assoc-let question-data
     (insert sx-question-mode-header-title
             (apply
              #'propertize
@@ -291,9 +296,12 @@ DATA can represent a question or an answer."
     (propertize .display_name
                 'face 'sx-question-mode-author)))
 
-(defun sx-question-mode--print-comment (data)
-  "Print the comment described by alist DATA."
-  (sx-assoc-let data
+(defun sx-question-mode--print-comment (comment-data)
+  "Print the comment described by alist COMMENT-DATA.
+
+The comment is printed according to
+`sx-question-mode-comments-format'."
+  (sx-assoc-let comment-data
     (insert
      (format
       sx-question-mode-comments-format
@@ -309,7 +317,10 @@ DATA can represent a question or an answer."
 
 (defmacro sx-question-mode--wrap-in-overlay (properties &rest body)
   "Execute BODY and wrap any inserted text in an overlay.
-Overlay is pushed on `sx-question-mode--overlays' and given PROPERTIES.
+
+Overlay is pushed on `sx-question-mode--overlays' and given
+PROPERTIES.
+
 Return the result of BODY."
   (declare (indent 1)
            (debug t))
@@ -323,9 +334,14 @@ Return the result of BODY."
      result))
 
 (defun sx-question-mode--insert-header (&rest args)
-  "Insert HEADER and VALUE.
-HEADER is given `sx-question-mode-header' face, and value is given FACE.
-\(fn header value face [header value face] [header value face] ...)"
+  "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.
+
+Use as (fn header value face
+          [header value face] ...)"
   (while args
     (insert
      (propertize (pop args) 'face 'sx-question-mode-header)
@@ -339,7 +355,7 @@ HEADER is given `sx-question-mode-header' face, and value is given FACE.
   "String to be displayed as the bullet of markdown list items.")
 
 (defun sx-question-mode--fill-and-fontify (text)
-  "Fill TEXT according to `markdown-mode' and return it."
+  "Return TEXT filled according to `markdown-mode'."
   (with-temp-buffer
     (erase-buffer)
     (insert text)
@@ -397,6 +413,7 @@ HEADER is given `sx-question-mode-header' face, and value is given FACE.
 
 (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
@@ -418,22 +435,23 @@ URL is used as 'help-echo and 'url properties."
    'action      #'sx-question-mode-follow-link))
 
 (defun sx-question-mode-follow-link (&optional pos)
-  "Follow link at POS or point"
+  "Follow link at POS.  If POS is nil, use `point'."
   (interactive)
   (browse-url
    (or (get-text-property (or pos (point)) 'url)
        (error "No url under point: %s" (or pos (point))))))
 
-(defun sx-question-mode-find-reference (id &optional id2)
+(defun sx-question-mode-find-reference (id &optional fallback-id)
   "Find url identified by reference ID in current buffer.
-If ID is nil, use ID2 instead."
+
+If ID is nil, use FALLBACK-ID instead."
   (save-excursion
     (save-match-data
       (goto-char (point-min))
       (when (search-forward-regexp
              (format (rx line-start (0+ blank) "[%s]:" (1+ blank)
                          (group-n 1 (1+ (not blank))))
-                     (or id id2))
+                     (or id fallback-id))
              nil t)
         (match-string-no-properties 1)))))
 
@@ -454,8 +472,10 @@ If ID is nil, use ID2 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.
+
 If nil, no recentering is performed."
   :type '(choice (const :tag "Don't recenter" nil)
                  integer)
@@ -463,6 +483,7 @@ 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)))
@@ -485,13 +506,16 @@ 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."
   (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.
+
 Return the new value of PROP at point.
+
 If DIRECTION is negative, move backwards instead."
   (let ((prop (intern (format "sx-question-mode--%s" prop)))
         (func (if (and (numberp direction)
@@ -525,8 +549,10 @@ If DIRECTION is negative, move backwards instead."
 
 ;;; Major-mode
 (define-derived-mode sx-question-mode markdown-mode "Question"
-  "Major mode for a question and its answers.
+  "Major mode to display and navigate a question and its answers.
+
 Letters do not insert themselves; instead, they are commands.
+
 \\<sx-question-mode>
 \\{sx-question-mode}"
   ;; Determine how to close this window.
@@ -559,6 +585,7 @@ 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 0342479..827b7c3 100644
--- a/sx-question.el
+++ b/sx-question.el
@@ -58,17 +58,18 @@ Return a list of questions, each consed with (site SITE).
       (page . ,page))
     sx-question-browse-filter)))
 
-(defun sx-question-get-question (site id)
-  "Query SITE for a question ID and return it.
+(defun sx-question-get-question (site question-id)
+  "Query SITE for a QUESTION-ID and return it.
 
-If ID doesn't exist on SITE, raise an error."
+If QUESTION-ID doesn't exist on SITE, raise an error."
   (let ((res (sx-method-call
-              (format "questions/%s" id)
+              (format "questions/%s" question-id)
               `((site . ,site))
               sx-question-browse-filter)))
     (if (vectorp res)
         (elt res 0)
-      (error "Couldn't find question %S in %S" id site))))
+      (error "Couldn't find question %S in %S"
+             question-id site))))
 
 
 ;;; Question Properties
diff --git a/sx-request.el b/sx-request.el
index 0434a7b..b3668fe 100644
--- a/sx-request.el
+++ b/sx-request.el
@@ -171,7 +171,9 @@ contains a 'vector'.  See `sx-request--build-keyword-arguments'."
       (concat base "?" args))))
 
 (defun sx-request--build-keyword-arguments (alist &optional kv-value-sep)
-  "Build a \"key=value&key=value&...\"-style string with the elements
+  "Format ALIST as a key-value joined with KV-VALUE-SEP.
+
+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
 be included in the return.  If you wish to pass a notion of
 false, use the symbol `false'.  Each element is processed with
diff --git a/sx-site.el b/sx-site.el
index 6bef91f..4e880b1 100644
--- a/sx-site.el
+++ b/sx-site.el
@@ -19,8 +19,6 @@
 
 ;;; Commentary:
 
-;;
-
 ;;; Code:
 
 (require 'sx-method)
@@ -43,7 +41,8 @@
      related_site.api_site_parameter
      related_site.relation)
     nil
-    none))
+    none)
+  "")
 
 (defun sx-site--get-site-list ()
   (sx-cache-get
@@ -54,7 +53,10 @@
 
 (defcustom sx-site-favorites
   nil
-  "Favorite sites."
+  "List of favorite sites.
+
+Each entry is a string corresponding to a single site's
+api_site_parameter."
   :group 'sx-site)
 
 (defun sx-site-get-api-tokens ()
diff --git a/sx-time.el b/sx-time.el
index 9c4dfaa..1ce0886 100644
--- a/sx-time.el
+++ b/sx-time.el
@@ -51,12 +51,14 @@
 
 (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 53aae84..eea0749 100644
--- a/sx.el
+++ b/sx.el
@@ -28,7 +28,7 @@
 ;;; Utility Functions
 
 (defun sx-message (format-string &rest args)
-  "Display a message"
+  "Display a message."
   (message "[stack] %s" (apply #'format format-string args)))
 
 (defun sx-message-help-echo ()
@@ -37,8 +37,9 @@
     (when echo (message "%s" echo))))
 
 (defun sx--thing-as-string (thing &optional sequence-sep)
-  "Return a string representation of THING.  If THING is already
-a string, just return it."
+  "Return a string representation of THING.
+
+If THING is already a string, just return it."
   (cond
    ((stringp thing) thing)
    ((symbolp thing) (symbol-name thing))
@@ -48,7 +49,24 @@ a string, just return it."
                thing (if sequence-sep sequence-sep ";")))))
 
 (defun sx--filter-data (data desired-tree)
-  "Filters DATA and returns the DESIRED-TREE"
+  "Filters DATA and returns the DESIRED-TREE.
+
+For example:
+
+  (sx--filter-data
+    '((prop1 . value1)
+      (prop2 . value2)
+      (prop3
+       (test1 . 1)
+       (test2 . 2))
+      (prop4 . t))
+    '(prop1 (prop3 test2)))
+
+would yeild
+
+  ((prop1 . value1)
+   (prop3
+    (test2 . 2)))"
   (if (vectorp data)
       (apply #'vector
              (mapcar (lambda (entry)
@@ -58,7 +76,7 @@ a string, just return it."
     (delq
      nil
      (mapcar (lambda (cons-cell)
-               ;; TODO the resolution of `f' is O(2n) in the worst
+               ;; @TODO the resolution of `f' is O(2n) in the worst
                ;; case.  It may be faster to implement the same
                ;; functionality as a `while' loop to stop looking the
                ;; list once it has found a match.  Do speed tests.
@@ -78,6 +96,7 @@ a string, just return it."
 ;;; 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
 symbol, the cdr is the symbol without the `.'."
   (cond
@@ -93,11 +112,12 @@ 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 while let-binding dotted symbols to their values in ALIST.
+  "Execute BODY with dotted symbols let-bound to their values in ALIST.
+
 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
+For instance, the following code
 
   (stack-core-with-data alist
     (list .title .body))
@@ -125,15 +145,17 @@ Run after `sx-init--internal-hook'.")
 This is used internally to set initial values for variables such
 as filters.")
 
-(defun sx--< (property x y &optional pred)
+(defun sx--< (property x y &optional predicate)
   "Non-nil if PROPERTY attribute of question X is less than that of Y.
-With optional argument predicate, use it instead of `<'."
-  (funcall (or pred #'<)
+
+With optional argument PREDICATE, use it instead of `<'."
+  (funcall (or predicate #'<)
            (cdr (assoc property x))
            (cdr (assoc property y))))
 
 (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
@@ -144,6 +166,9 @@ SETTER should be a function of two arguments.  If SETTER is nil,
   nil)
 
 (defun stack-initialize ()
+  "Initialize SX.
+
+Runs `sx-init--internal-hook' and `sx-init-hook', in that order."
   (run-hooks
    'sx-init--internal-hook
    'sx-init-hook))