Provide commentaries for each file

13 files changed, 55 insertions, 6 deletions

diff --git a/sx-auth.el b/sx-auth.el
index bfa805a..427900d 100644
--- a/sx-auth.el
+++ b/sx-auth.el
@@ -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)
diff --git a/sx-cache.el b/sx-cache.el
index 51c2267..cf48ef5 100644
--- a/sx-cache.el
+++ b/sx-cache.el
@@ -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:
 
diff --git a/sx-encoding.el b/sx-encoding.el
index 0e66677..36cf03f 100644
--- a/sx-encoding.el
+++ b/sx-encoding.el
@@ -19,6 +19,11 @@
 
 ;;; 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)
diff --git a/sx-favorites.el b/sx-favorites.el
index d5c5a4f..44ee19f 100644
--- a/sx-favorites.el
+++ b/sx-favorites.el
@@ -19,6 +19,9 @@
 
 ;;; Commentary:
 
+;; This file provides logic for retrieving and managing a user's
+;; starred questions.
+
 ;;; Code:
 
 (require 'sx-method)
diff --git a/sx-filter.el b/sx-filter.el
index d973f2a..327a8eb 100644
--- a/sx-filter.el
+++ b/sx-filter.el
@@ -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:
 
 
diff --git a/sx-interaction.el b/sx-interaction.el
index a50e718..0e4aae9 100644
--- a/sx-interaction.el
+++ b/sx-interaction.el
@@ -19,6 +19,10 @@
 
 ;;; Commentary:
 
+;; This file provides voting, commenting, and other interactive
+;; facilities.  Most functions are scoped relative to `sx--data-here'
+;; when called interactively.
+
 
 ;;; Code:
 
diff --git a/sx-networks.el b/sx-networks.el
index dda6dd5..5f5f1c3 100644
--- a/sx-networks.el
+++ b/sx-networks.el
@@ -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)
diff --git a/sx-question-list.el b/sx-question-list.el
index 7caa03d..0967d6a 100644
--- a/sx-question-list.el
+++ b/sx-question-list.el
@@ -19,6 +19,8 @@
 
 ;;; Commentary:
 
+;; Provides question list logic (as used in e.g. `sx-tab-frontpage').
+
 ;;; Code:
 (require 'tabulated-list)
 (require 'cl-lib)
diff --git a/sx-question-mode.el b/sx-question-mode.el
index c3e7eac..ff13ede 100644
--- a/sx-question-mode.el
+++ b/sx-question-mode.el
@@ -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:
 (require 'markdown-mode)
diff --git a/sx-question.el b/sx-question.el
index 01ba030..680eaaf 100644
--- a/sx-question.el
+++ b/sx-question.el
@@ -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:
 
diff --git a/sx-site.el b/sx-site.el
index df02f7e..1ed469a 100644
--- a/sx-site.el
+++ b/sx-site.el
@@ -19,6 +19,9 @@
 
 ;;; Commentary:
 
+;; This file provides various pieces of site logic, such as retrieving
+;; the list of sites and the list of a user's favorited questions.
+
 ;;; Code:
 
 (require 'sx-method)
diff --git a/sx-tab.el b/sx-tab.el
index bbbdb79..16b1737 100644
--- a/sx-tab.el
+++ b/sx-tab.el
@@ -19,7 +19,12 @@
 
 ;;; Commentary:
 
-;;
+;; This file provides a single macro to define 'tabs' to view lists of
+;; questions.
+
+;;; Tabs:
+
+;; - frontpage :: the frontpage of a single site
 
 
 ;;; Code:
diff --git a/sx-time.el b/sx-time.el
index e65bb50..8f90747 100644
--- a/sx-time.el
+++ b/sx-time.el
@@ -19,7 +19,8 @@
 
 ;;; Commentary:
 
-;;
+;; This file provides functions for manipulating and displaying
+;; timestamps.
 
 ;;; Code: