Organize

.gitignore

@@ -1,12 +1,18 @@
-# Emacs backup files
+# Personal Development
+.dir-locals.el
+
+# Backup Files
 *~
 \#*\#
 
 # Compiled Elisp
 *.elc
+
+# Package Artifacts
 /.cask/
-.dir-locals.el
-/.stackmode/
 /url/
+/.sx/
+
+# Generated Files
 /sx.info
 /sx.texi

Makefile

@@ -33,7 +33,3 @@ install_cask:
 
 install_evm:
 	curl -fsSkL https://raw.github.com/rejeep/evm/master/go | bash
-
-# Local Variables:
-# indent-tabs-mode: t
-# End:

sx-auth.el

@@ -1,4 +1,4 @@
-;;; sx-auth.el --- user authentication  -*- lexical-binding: t; -*-
+;;; sx-auth.el --- user authentication               -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Sean Allred
 
@@ -19,6 +19,13 @@
 
 ;;; Commentary:
 
+;; This file handles logic related to authentication.  This includes
+;; determining if a certain filter requires authentication (via the
+;; variable `sx-auth-filter-auth' and function `sx-auth--filter-p'),
+;; determining if a method requires authentication (via the variable
+;; `sx-auth-method-auth' and function `sx-auth--method-p'), and
+;; actually authenticating the user (with `sx-auth-authenticate').
+
 ;;; Code:
 
 (require 'sx)
@@ -36,7 +43,9 @@
   "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!")
+what you are doing!
+
+This variable is set with `sx-auth-authenticate'.")
 
 (defvar sx-auth-method-auth '((me . t)
                               (inbox . t)
@@ -65,20 +74,20 @@ what you are doing!")
                                          upvote
                                          (unanswered my-tags)))
   "List of methods that require auth.
-Methods are of form (METHOD SUBMETHODS) where SUBMETHODS
-  is (METHOD METHOD METHOD ...).
+Methods are of the form \(METHOD . SUBMETHODS) where SUBMETHODS
+  is \(METHOD METHOD METHOD ...).
 
 If all SUBMETHODS require auth or there are no submethods, form
-will be (METHOD  . t)")
+will be \(METHOD . t)")
 
 (defvar sx-auth-filter-auth '(question.upvoted
                               question.downvoted
                               answer.upvoted
                               answer.downvoted
                               comment.upvoted)
   "List of filter types that require auth.
-Keywords are of form (OBJECT TYPES) where TYPES is (FILTER FILTER
-FILTER).")
+Keywords are of the form \(OBJECT TYPES) where TYPES is \(FILTER
+FILTER FILTER).")
 
 ;;;###autoload
 (defun sx-authenticate ()

sx-babel.el

@@ -1,4 +1,4 @@
-;;; sx-babel.el --- Font-locking pre blocks according to language. -*- lexical-binding: t; -*-
+;;; sx-babel.el --- font-locking pre blocks according to language  -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Artur Malabarba
 
@@ -122,3 +122,6 @@ Returns the amount of indentation removed."
 (provide 'sx-babel)
 ;;; sx-babel.el ends here
 
+;; Local Variables:
+;; indent-tabs-mode: nil
+;; End:

sx-button.el

@@ -1,4 +1,4 @@
-;;; sx-button.el --- Defining buttons used throughout SX. -*- lexical-binding: t; -*-
+;;; sx-button.el --- defining buttons                -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Artur Malabarba
 
@@ -163,3 +163,7 @@ usually part of a code-block."
 
 (provide 'sx-button)
 ;;; sx-button.el ends here
+
+;; Local Variables:
+;; indent-tabs-mode: nil
+;; End:

sx-cache.el

@@ -1,4 +1,4 @@
-;;; sx-cache.el --- caching -*- lexical-binding: t; -*-
+;;; sx-cache.el --- caching                          -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Sean Allred
 
@@ -19,12 +19,18 @@
 
 ;;; Commentary:
 
-;; All caches are retrieved and set using symbols.  The symbol should
-;; be the sub-subpackage that is using the cache.  For example,
-;; `sx-pkg' would use `(sx-cache-get 'pkg)'.
+;; This file handles the cache system.  All caches are retrieved and
+;; set using symbols.  The symbol should be the sub-package that is
+;; using the cache.  For example, `sx-pkg' would use
+;;
+;;   `(sx-cache-get 'pkg)'
 ;;
 ;; This symbol is then converted into a filename within
-;; `sx-cache-directory'.
+;; `sx-cache-directory' using `sx-cache-get-file-name'.
+;;
+;; Currently, the cache is written at every `sx-cache-set', but this
+;; write will eventually be done by some write-all function which will
+;; be set on an idle timer.
 
 ;;; Code:
 

sx-compose.el

@@ -1,4 +1,4 @@
-;;; sx-compose.el --- Major-mode for coposing questions and answers. -*- lexical-binding: t; -*-
+;;; sx-compose.el --- major-mode for composing questions and answers  -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Artur Malabarba
 
@@ -302,3 +302,7 @@ the id property."
 
 (provide 'sx-compose)
 ;;; sx-compose.el ends here
+
+;; Local Variables:
+;; indent-tabs-mode: nil
+;; End:

sx-encoding.el

@@ -1,4 +1,4 @@
-;;; sx-encoding.el --- encoding -*- lexical-binding: t; -*-
+;;; sx-encoding.el --- encoding                      -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Sean Allred
 
@@ -19,10 +19,18 @@
 
 ;;; Commentary:
 
+;; This file handles decoding the responses we get from the API.  They
+;; are received either as plain-text or as a `gzip' compressed archive.
+;; For this, `sx-encoding-gzipped-p' is used to determine if content
+;; has been compressed under `gzip'.
+
 ;;; Code:
 
 (require 'cl-lib)
 
+
+;;;; HTML Encoding
+
 (defcustom sx-encoding-html-entities-plist
   '(Aacute "Á" aacute "á" Acirc "Â" acirc "â" acute "´" AElig "Æ" aelig "æ"
            Agrave "À" agrave "à" alefsym "ℵ" Alpha "Α" alpha "α" amp "&" and "∧"
@@ -86,6 +94,9 @@ Return the decoded string."
                     (substring ss 1))))))))
     (replace-regexp-in-string "&[^; ]*;" get-function string)))
 
+
+;;;; Convenience Functions
+
 (defun sx-encoding-normalize-line-endings (string)
   "Normalize the line endings for STRING.
 The API returns strings that use Windows-style line endings.
@@ -131,6 +142,9 @@ some cases."
       (cl-map #'vector #'sx-encoding-clean-content-deep data))
      (t data))))
 
+
+;;;; GZIP
+
 (defun sx-encoding-gzipped-p (data)
   "Check for magic bytes in DATA.
 Check if the first two bytes of a string in DATA match the magic

sx-favorites.el

@@ -1,4 +1,4 @@
-;;; sx-favorites.el --- Starred questions          -*- lexical-binding: t; -*-
+;;; sx-favorites.el --- starred questions            -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Sean Allred
 
@@ -19,6 +19,9 @@
 
 ;;; Commentary:
 
+;; This file provides logic for retrieving and managing a user's
+;; starred questions.
+
 ;;; Code:
 
 (require 'sx-method)

sx-filter.el

@@ -1,4 +1,4 @@
-;;; sx-filter.el --- Handles retrieval of filters.                         -*- lexical-binding: t; -*-
+;;; sx-filter.el --- handles retrieval of filters    -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Sean Allred
 
@@ -19,6 +19,10 @@
 
 ;;; Commentary:
 
+;; This file manages filters and provides an API to compile filters
+;; and retrieve them from the cache.  See `sx-filter-compile' and
+;; `sx-filter-get-var', respectively.
+
 ;;; Code:
 
 

sx-inbox.el

@@ -1,4 +1,4 @@
-;;; sx-inbox.el --- Base inbox logic. -*- lexical-binding: t; -*-
+;;; sx-inbox.el --- base inbox logic                 -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Artur Malabarba
 

sx-interaction.el

@@ -1,4 +1,4 @@
-;;; sx-interaction.el --- Voting, commenting, and otherwise interacting with questions.  -*- lexical-binding: t; -*-
+;;; sx-interaction.el --- voting, commenting, and other interaction  -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Artur Malabarba
 
@@ -443,3 +443,7 @@ context at point. "
 
 (provide 'sx-interaction)
 ;;; sx-interaction.el ends here
+
+;; Local Variables:
+;; indent-tabs-mode: nil
+;; End:

sx-load.el

@@ -1,4 +1,4 @@
-;;; sx-load.el --- Load all files of the sx package. -*- lexical-binding: t; -*-
+;;; sx-load.el --- load all files of the SX package  -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Artur Malabarba
 

sx-method.el

@@ -1,4 +1,4 @@
-;;; sx-method.el --- Main interface for API method calls. -*- lexical-binding: t; -*-
+;;; sx-method.el --- method calls                    -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Sean Allred
 
@@ -144,3 +144,7 @@ Return the entire response as a complex alist."
 
 (provide 'sx-method)
 ;;; sx-method.el ends here
+
+;; Local Variables:
+;; indent-tabs-mode: nil
+;; End:

sx-networks.el

@@ -1,4 +1,4 @@
-;;; sx-networks.el --- user network information  -*- lexical-binding: t; -*-
+;;; sx-networks.el --- user network information      -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Sean Allred
 
@@ -19,6 +19,9 @@
 
 ;;; Commentary:
 
+;; This file provides logic for retrieving information about the user
+;; across the entire network, e.g. their registered sites.
+
 ;;; Code:
 
 (require 'sx-method)

sx-notify.el

@@ -1,4 +1,4 @@
-;;; sx-notify.el --- Mode-line notifications. -*- lexical-binding: t; -*-
+;;; sx-notify.el --- mode-line notifications         -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Artur Malabarba
 

sx-question-list.el

@@ -1,4 +1,4 @@
-;;; sx-question-list.el --- Major-mode for navigating questions list.  -*- lexical-binding: t; -*-
+;;; sx-question-list.el --- major-mode for navigating questions list  -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Artur Malabarba
 
@@ -19,6 +19,8 @@
 
 ;;; Commentary:
 
+;; Provides question list logic (as used in e.g. `sx-tab-frontpage').
+
 ;;; Code:
 (require 'tabulated-list)
 (require 'cl-lib)
@@ -606,3 +608,7 @@ Sets `sx-question-list--site' and then call
 
 (provide 'sx-question-list)
 ;;; sx-question-list.el ends here
+
+;; Local Variables:
+;; indent-tabs-mode: nil
+;; End:

sx-question-mode.el

@@ -1,4 +1,4 @@
-;;; sx-question-mode.el --- Major-mode for displaying a question. -*- lexical-binding: t; -*-
+;;; sx-question-mode.el --- major-mode for displaying questions  -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Artur Malabarba
 
@@ -19,6 +19,9 @@
 
 ;;; Commentary:
 
+;; This file provides a means to print questions with their answers
+;; and all comments.  See the customizable group `sx-question-mode'.
+
 
 ;;; Code:
 (eval-when-compile
@@ -271,3 +274,7 @@ query the api."
 
 (provide 'sx-question-mode)
 ;;; sx-question-mode.el ends here
+
+;; Local Variables:
+;; indent-tabs-mode: nil
+;; End:

sx-question-print.el

@@ -1,4 +1,4 @@
-;;; sx-question-print.el --- Populating the question-mode buffer with content. -*- lexical-binding: t; -*-
+;;; sx-question-print.el --- populating the question-mode buffer with content  -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Artur Malabarba
 
@@ -468,3 +468,7 @@ font-locking."
 
 (provide 'sx-question-print)
 ;;; sx-question-print.el ends here
+
+;; Local Variables:
+;; indent-tabs-mode: nil
+;; End:

sx-question.el

@@ -1,4 +1,4 @@
-;;; sx-question.el --- Base question logic. -*- lexical-binding: t; -*-
+;;; sx-question.el --- question logic                -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Sean Allred
 
@@ -19,6 +19,9 @@
 
 ;;; Commentary:
 
+;; Thie file provides an API for retrieving questions and defines
+;; additional logic for marking questions as read or hidden.
+
 
 ;;; Code:
 

sx-request.el

@@ -1,4 +1,4 @@
-;;; sx-request.el --- Requests and url manipulation.  -*- lexical-binding: t; -*-
+;;; sx-request.el --- requests and url manipulation  -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014  Sean Allred
 
@@ -256,3 +256,7 @@ false, use the symbol `false'.  Each element is processed with
 
 (provide 'sx-request)
 ;;; sx-request.el ends here
+
+;; Local Variables:
+;; indent-tabs-mode: nil
+;; End: