about summary refs log tree commit homepage
path: root/lib/msgthr/container.rb
diff options
context:
space:
mode:
Diffstat (limited to 'lib/msgthr/container.rb')
-rw-r--r--lib/msgthr/container.rb32
1 files changed, 25 insertions, 7 deletions
diff --git a/lib/msgthr/container.rb b/lib/msgthr/container.rb
index 30f6775..e51507c 100644
--- a/lib/msgthr/container.rb
+++ b/lib/msgthr/container.rb
@@ -1,8 +1,13 @@
 # Copyright (C) 2016 all contributors <msgthr-public@80x24.org>
 # License: GPL-2.0+ <https://www.gnu.org/licenses/gpl-2.0.txt>
 
-# An internal container class, this is exposed for sorting APIs
-# but should not be initialized in your own code.
+# An internal container class, this is exposed for Msgthr#order!
+# and Msgthr#walk_thread APIs.  They should should not be initialized
+# in your own code.
+#
+# One container object will exist for every message you call Msgthr#add! on,
+# so there can potentially be many of these objects for large sets of
+# messages.
 class Msgthr::Container
 
   # Unique message identifier, typically the Message-Id header for mail
@@ -11,21 +16,33 @@ class Msgthr::Container
   attr_reader :mid
 
   # Opaque data pointer, may be used by the user for any purpose.
-  # This may be +nil+ to denote missing (aka "ghost") messages.
+  # This is +nil+ to denote missing (aka "ghost") messages.
   attr_accessor :msg
 
-  attr_accessor :children # :nodoc:
+  # You probably do not need to use this.
+  # It is only safe to access this after Msgthr#order!
+  # This contains an Array of Msgthr::Container objects which have the
+  # +parent+ field pointing to us
+  attr_accessor :children
+
+  # You probably do not need to use this; and you should only use
+  # this after Msgthr#order!  This points to the +parent+ of the
+  # message if one exists, and +nil+ if a message has no parent.
+  # This will only be accurate once all messages are added to
+  # a Msgthr set via Msgthr#add
   attr_accessor :parent # :nodoc:
 
   def initialize(mid) # :nodoc:
     @mid = mid
     @children = {} # becomes an Array after order!
     @parent = nil
-    @msg = nil # opaque
+    @msg = nil # opaque pointer supplied by user
   end
 
-  # returns the topmost message container with an opaque message pointer
-  # in it.  This may be +nil+ if none are available.
+  # Returns the topmost message container with an opaque message pointer
+  # in it.  This may be +nil+ if no message is available.
+  # This is preferable to using the container yielded by Msgthr#order!
+  # directly when handling incomplete message sets.
   def topmost
     q = [ self ]
     while cont = q.shift
@@ -55,6 +72,7 @@ class Msgthr::Container
     false
   end
 
+  # only called by Msgthr#order!
   def order! # :nodoc:
     seen = { @mid => true }
     q = [ self ]