Improved model documentation.

diff --git a/elpher.el b/elpher.el
index 6f586f1..96e0a86 100644 (file)
--- a/elpher.el
+++ b/elpher.el
@@ -403,6 +403,17 @@ If no address is defined, returns 0.  (This is for compatibility with the URL li
 
 ;; Cache
 
+;; We use the following pair of hashmaps to form the cache: one
+;; for the content (rendered server responses), and one for the
+;; position of point within the content.
+;;
+;; The keys for both of these hashmaps are the page addresses, and
+;; the cache persists for as long as the emacs session.
+;;
+;; Whether or not to use cached content is a decision made by the
+;; specific renderer.  Some renderers, such as elpher-render-download,
+;; never cache.
+
 (defvar elpher-content-cache (make-hash-table :test 'equal))
 (defvar elpher-pos-cache (make-hash-table :test 'equal))
 
@@ -425,6 +436,11 @@ If no address is defined, returns 0.  (This is for compatibility with the URL li
 
 ;; Page
 
+;; In our model, a "page" merely represents a combination of a
+;; display string and an elpher address.  The distinction exists
+;; because caching, server response acquisition, etc deal only
+;; with addresses.
+
 (defun elpher-make-page (display-string address)
   "Create a page with DISPLAY-STRING and ADDRESS."
   (list display-string address))