Document controller class better, move to_gem_version to helpers

lib/rtasklib/controller.rb

@@ -3,6 +3,10 @@
 
 module Rtasklib
 
+  # Accessed through the main TW, which includes this module.
+  # Ideally should only be the well documented public, user-facing methods.
+  # We're getting there.
+  # XXX: depends on @override_a currently, which isn't great.
   module Controller
     extend self
 
@@ -20,18 +24,29 @@ def all
       all
     end
 
+    # Converts ids, tags, and dom queries to a single string ready to pass
+    # directly to task.
+    #
+    # @param ids[Range, Array<String>, String, Fixnum]
+    # @param tags[String, Array<String>]
+    # @param dom[String, Array<String>]
+    # @return [String] "#{id_s} #{tag_s} #{dom_s}"
     def filter ids: nil, tags: nil, dom: nil
+      id_s = tag_s = dom_s = ""
       ids  = process_ids(ids)   unless ids.nil?
       tags = process_tags(tags) unless tags.nil?
       dom  = process_dom(dom)   unless dom.nil?
-      f = ""
+      return "#{id_s} #{tag_s} #{dom_s}"
     end
     private :filter
 
+    # Converts arbitrary id input to a task safe string
+    #
+    # @param ids[Range, Array<String>, String, Fixnum]
     def process_ids ids
       case ids
       when Range
-        ids.to_a.join(",")
+        id_range_to_s(ids)
       when Array
         ids.join(",")
       when String
@@ -42,6 +57,20 @@ def process_ids ids
     end
     private :process_ids
 
+    # Convert a range to a comma separated strings, e.g. 1..4 -> "1,2,3,4"
+    #
+    # @param id_range [Range]
+    # @return [Array<String>]
+    def id_range_to_s id_range
+      id_range.to_a.join(",")
+    end
+    private :id_range_to_s
+
+    def id_a_to_s id_a
+      ids.to_a.join(",")
+    end
+    private :id_range_to_s
+
     def process_tags tags
     end
 
@@ -153,6 +182,11 @@ def create_uda name, type: "string", label: nil, values: nil,
       update_config "uda.#{name}.urgency", urgency unless urgency.nil?
     end
 
+    # Calls `task _show` with initial overrides returns a Taskrc object of the
+    # result
+    #
+    # @return [Taskrc]
+    # @api public
     def get_rc
       res = []
       Execute.task_popen3(*@override_a, "_show") do |i, o, e, t|
@@ -161,21 +195,16 @@ def get_rc
       Taskrc.new(res, :array)
     end
 
+    # Calls `task _version` and returns the result
+    #
+    # @return [String]
+    # @api public
     def get_version
       version = nil
-      Execute.task_popen3(*@override_a, "_version") do |i, o, e, t|
-        version = to_gem_version(o.read.chomp)
+      Execute.task_popen3("_version") do |i, o, e, t|
+        version = Helpers.to_gem_version(o.read.chomp)
       end
       version
     end
-
-    # Converts a string of format "1.6.2 (adf342jsd)" to Gem::Version object
-    #
-    #
-    def to_gem_version raw
-      std_ver = raw.chomp.gsub(' ','.').delete('(').delete(')')
-      Gem::Version.new std_ver
-    end
-    private :to_gem_version
   end
 end

lib/rtasklib/helpers.rb

@@ -1,6 +1,8 @@
 
 module Rtasklib
 
+  # A collection of stateless, non-end-user facing functions available
+  # throughout the library
   module Helpers
     # make this module a stateless, singleton
     extend self
@@ -13,7 +15,24 @@ module Helpers
     #   and joined with ","
     #   [1...5, 8, 9] : "1-5,8,9"
 
+    # Converts a string of format "1.6.2 (adf342jsd)" to Gem::Version object
+    #
+    # @param raw [String]
+    # @return [Gem::Version]
+    def to_gem_version raw
+      std_ver = raw.chomp.gsub(' ','.').delete('(').delete(')')
+      Gem::Version.new std_ver
+    end
+    private :to_gem_version
+
+    # Determine the type that a value should be coerced to
     # Int needs to precede float because ints are also floats
+    # Doesn't detect arrays, b/c task stores these as comma separated strings
+    # which could just as easily be Strings....
+    # If nothing works it defaults to String.
+    #
+    # @param value [Object] anything that needs to be coerced, probably string
+    # @return [Axiom::Types::Boolean, Integer, Float, String]
     def determine_type value
       if boolean? value
         return Axiom::Types::Boolean