From 1b633959b1153b40ff8fcddd8430e0c6b0e9574b Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Thu, 8 Jun 2017 23:37:05 +0000 Subject: improve API documentation and testing Oh, so that's why I hadn't released this project earlier... --- lib/msgthr/container.rb | 32 +++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) (limited to 'lib/msgthr') 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 # License: GPL-2.0+ -# 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 ] -- cgit v1.2.3-24-ge0c7