sup

commit 6718c565bf71956f38914e5ebd1d4ca1d34bef59
parent 07763b0a4c7fdb2481f6fb11672124de9896a19d
Author: Gaute Hope <eg@gaute.vetsj.com>
Date:   Mon, 29 Jul 2013 12:06:20 +0200

Update source.rb documentation comments

commit ecdda4e0510d8d1ff574d6cf1e9941789e84a037
Author: Gaute Hope 
Date:   Mon Jul 29 09:27:24 2013 +0200

    refactor

commit 93b362add9f67a3eb6efb4e5b0bfcacb9288af4a
Author: Gaute Hope 
Date:   Mon Jul 29 09:22:52 2013 +0200

    Update source.rb documentation comments

Diffstat:

1 file changed, 10 insertions(+), 18 deletions(-)
diff --git a/lib/sup/source.rb b/lib/sup/source.rb
@@ -22,30 +22,23 @@ class Source
   ## read, delete them, or anything else. (Well, it's nice to be able
   ## to delete them, but that is optional.)
   ##
-  ## On the other hand, Sup assumes that you can assign each message a
-  ## unique integer id, such that newer messages have higher ids than
-  ## earlier ones, and that those ids stay constant across sessions
-  ## (in the absence of some other client going in and fucking
-  ## everything up). For example, for mboxes I use the file offset of
-  ## the start of the message. If a source does NOT have that
-  ## capability, e.g. IMAP, then you have to do a little more work to
-  ## simulate it.
+  ## Messages are identified internally based on the message id, and stored
+  ## with an unique document id. Along with the message, source information
+  ## that can contain arbitrary fields (set up by the source) is stored. This
+  ## information will be passed back to the source when a message in the
+  ## index (Sup database) needs to be identified to its source, e.g. when
+  ## re-reading or modifying a unique message.
   ##
   ## To write a new source, subclass this class, and implement:
   ##
-  ## - start_offset
-  ## - end_offset (exclusive!) (or, #done?)
+  ## - initialize
   ## - load_header offset
   ## - load_message offset
   ## - raw_header offset
   ## - raw_message offset
-  ## - check (optional)
+  ## - store_message (optional)
+  ## - poll (loads new messages)
   ## - go_idle (optional)
-  ## - next (or each, if you prefer): should return a message and an
-  ##   array of labels.
-  ##
-  ## ... where "offset" really means unique id. (You can tell I
-  ## started with mbox.)
   ##
   ## All exceptions relating to accessing the source must be caught
   ## and rethrown as FatalSourceErrors or OutOfSyncSourceErrors.
@@ -57,8 +50,7 @@ class Source
   ## Finally, be sure the source is thread-safe, since it WILL be
   ## pummelled from multiple threads at once.
   ##
-  ## Examples for you to look at: mbox/loader.rb, imap.rb, and
-  ## maildir.rb.
+  ## Examples for you to look at: mbox.rb and maildir.rb.
 
   bool_accessor :usual, :archived
   attr_reader :uri