Improve (a lot) the documentation

.gitignore

@@ -4,3 +4,5 @@ Gemfile.lock
 pkg/*
 coverage/*
 tmp/*
+doc/
+.yardoc/

lib/todotxt.rb

@@ -2,6 +2,8 @@
 libdir = File.dirname(__FILE__)
 $LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
 
+
+# Todotxt is a Ruby librairy / CLI interface to work with a [todo.txt](http://www.todotxt.com) format.
 module Todotxt
   autoload :Todo,       'todotxt/todo'
   autoload :TodoList,   'todotxt/todolist'

lib/todotxt/config.rb

@@ -2,6 +2,12 @@
 require 'fileutils'
 
 module Todotxt
+  # Todotxt relies on a configuration file (`.todotxt.cfg`) in your home directory,
+  # which points to the location of your todo.txt. You can run:
+  #
+  #    $ todotxt generate_cfg
+  #
+  # to generate this file, which will then point to `~/todo.txt`.
   class Config < ParseConfig
     def initialize(options = {})
       @options = options

lib/todotxt/todo.rb

@@ -1,6 +1,15 @@
 require 'todotxt/regex'
 
 module Todotxt
+  # Represent a task formated according
+  # [todo.txt format rules](https://github.com/todotxt/todo.txt#todotxt-format-rules)
+  #
+  # @attr [String] text reprensent all text definition of this task
+  # @attr [Integer] line the line number of this task
+  # @attr [Char] priority the letter who define pritority
+  # @attr [Array] projects list of linked projects
+  # @attr [Array] contexts list of linked contexts
+  # @attr [Boolean] done `true` if task is done
   class Todo
     attr_accessor :text
     attr_accessor :line
@@ -9,32 +18,29 @@ class Todo
     attr_accessor :contexts
     attr_accessor :done
 
+    # @param[String] text
     def initialize(text, line = nil)
       @line = line
 
       create_from_text text
     end
 
-    def create_from_text(text)
-      @text = text
-      @priority = text.scan(PRIORITY_REGEX).flatten.first || nil
-      @projects = text.scan(PROJECT_REGEX).flatten.uniq   || []
-      @contexts = text.scan(CONTEXT_REGEX).flatten.uniq   || []
-      @done = !text.scan(DONE_REGEX).empty?
-    end
-
+    # Get due date if set
+    # @return [Date|Nil]
     def due
       date = Chronic.parse(text.scan(DATE_REGEX).flatten[2])
       date.nil? ? nil : date.to_date
     end
 
+    # Mark this task as done
     def do
       unless done
         @text = "x #{text}".strip
         @done = true
       end
     end
 
+    # Mark this task as undone
     def undo
       if done
         @text = text.sub(DONE_REGEX, '').strip
@@ -58,10 +64,12 @@ def prioritize(new_priority = nil, opts = {})
       @priority = new_priority
     end
 
+    # Add some content to the task
     def append(appended_text = '')
       @text << ' ' << appended_text
     end
 
+    # Add some content to the task
     def prepend(prepended_text = '')
       @text = "#{prepended_text} #{text.gsub(PRIORITY_REGEX, '')}"
       prioritize priority, force: true
@@ -71,17 +79,31 @@ def replace(text)
       create_from_text text
     end
 
+    # @return [String]
     def to_s
       text.clone
     end
 
+    # Compare another `Todo` according to their `line` and `priority` attribute.
+    # @param [Todo] b
     def <=>(b)
+      return 1 unless b.is_a? Todo
       return line <=> b.line if priority.nil? && b.priority.nil?
 
       return 1 if priority.nil?
       return -1 if b.priority.nil?
 
       priority <=> b.priority
     end
+
+    private
+
+    def create_from_text(text)
+      @text = text
+      @priority = text.scan(PRIORITY_REGEX).flatten.first || nil
+      @projects = text.scan(PROJECT_REGEX).flatten.uniq   || []
+      @contexts = text.scan(CONTEXT_REGEX).flatten.uniq   || []
+      @done = !text.scan(DONE_REGEX).empty?
+    end
   end
 end

lib/todotxt/todolist.rb

@@ -1,11 +1,12 @@
 require 'todotxt/todo'
 
 module Todotxt
-  # @TODO merge with TodoFile, both overlap too much
+  # Represent a collection of `Todo`
+  # TODO merge with TodoFile, both overlap too much
   class TodoList
     include Enumerable
 
-    attr_accessor :todos
+    attr_reader :todos
 
     # @INK: refactor TodoList and TodoFile
     #   So that TodoFile contains all IO ad List is no longer dependent on file.
@@ -21,6 +22,8 @@ def initialize(file, line = nil)
       end
     end
 
+    # @param [String] str add the given todo string definition to the list
+    # TODO also support `Todo` object
     def add(str)
       todo = Todo.new str, (@line += 1)
       @todos.push todo
@@ -29,6 +32,7 @@ def add(str)
       todo
     end
 
+    # @param [Todo|String] line remove the given todo to the list
     def remove(line)
       @todos.reject! { |t| t.line.to_s == line.to_s }
     end
@@ -38,10 +42,14 @@ def move(line, other_list)
       remove line
     end
 
+    # Get all existing projects into todos
+    # @return[Array<String>]
     def projects
       map(&:projects).flatten.uniq.sort
     end
 
+    # Get all existing contects into todos
+    # @return[Array<String>]
     def contexts
       map(&:contexts).flatten.uniq.sort
     end