From 0228524a31cf2e040525302da8cf12e2f749fbbb Mon Sep 17 00:00:00 2001 From: Sean Allred Date: Fri, 28 Nov 2014 13:30:11 -0500 Subject: Provide commentaries for each file --- sx-auth.el | 7 +++++++ sx-cache.el | 14 ++++++++++---- sx-encoding.el | 5 +++++ sx-favorites.el | 3 +++ sx-filter.el | 4 ++++ sx-interaction.el | 4 ++++ sx-networks.el | 3 +++ sx-question-list.el | 2 ++ sx-question-mode.el | 3 +++ sx-question.el | 3 +++ sx-site.el | 3 +++ sx-tab.el | 7 ++++++- sx-time.el | 3 ++- 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: -- cgit v1.2.3