Merge pull request #77 from vermiculus/documentation

Documentation

1 files changed, 37 insertions, 16 deletions

diff --git a/sx.el b/sx.el
index eab1ead..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 ()
@@ -72,7 +73,9 @@ 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 elements of a sequence."
+
+Optional argument SEQUENCE-SEP is the separator applied between
+elements of a sequence."
   (cond
    ((stringp thing) thing)
    ((symbolp thing) (symbol-name thing))
@@ -82,7 +85,24 @@ Optional argument SEQUENCE-SEP is the separator applied between elements of a se
                thing (if sequence-sep sequence-sep ";")))))
 
 (defun sx--filter-data (data desired-tree)
-  "Filters DATA and return the DESIRED-TREE."
+  "Filter DATA and return the DESIRED-TREE.
+
+For example:
+
+  (sx--filter-data
+    '((prop1 . value1)
+      (prop2 . value2)
+      (prop3
+       (test1 . 1)
+       (test2 . 2))
+      (prop4 . t))
+    '(prop1 (prop3 test2)))
+
+would yield
+
+  ((prop1 . value1)
+   (prop3
+    (test2 . 2)))"
   (if (vectorp data)
       (apply #'vector
              (mapcar (lambda (entry)
@@ -92,7 +112,7 @@ Optional argument SEQUENCE-SEP is the separator applied between elements of a se
     (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.
@@ -112,7 +132,7 @@ Optional argument SEQUENCE-SEP is the separator applied between elements of a se
 ;;; 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)
@@ -127,13 +147,13 @@ 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.
-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
+For instance, the following code
 
-  (stack-core-with-data alist
+  (sx-assoc-let alist
     (list .title .body))
 
 is equivalent to
@@ -150,19 +170,19 @@ is equivalent to
 
 (defcustom sx-init-hook nil
   "Hook run when stack-mode initializes.
-
-Run after `sx-init--internal-hook'.")
+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 pred)
+(defun sx--< (property x y &optional predicate)
   "Non-nil if PROPERTY attribute of alist X is less than that of Y.
-With optional argument PRED, 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))))
 
@@ -184,6 +204,7 @@ 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."
   (when (or force (not sx-initialized))
     (prog1