Put down the last C and B grade objects (inch - documentation)

8 files changed, 32 insertions, 9 deletions

diff --git a/lib/highline.rb b/lib/highline.rb
index d49016c..ba409b6 100755
--- a/lib/highline.rb
+++ b/lib/highline.rb
@@ -209,9 +209,7 @@ class HighLine
   #
   # Raises EOFError if input is exhausted.
   #
-  # @param template_or_question [String, Question] what to ask
-  # @param answer_type [Class] to what class to convert the answer
-  # @param details to be passed to Question.build
+  # @param (see Question.build)
   # @return answer converted to the class in answer_type
   def ask(template_or_question, answer_type = nil, &details)
     question = Question.build(template_or_question, answer_type, &details)
diff --git a/lib/highline/compatibility.rb b/lib/highline/compatibility.rb
index bcc2907..33c889c 100644
--- a/lib/highline/compatibility.rb
+++ b/lib/highline/compatibility.rb
@@ -3,11 +3,13 @@
 unless STDIN.respond_to? :getbyte
   # HighLine adds #getbyte alias to #getc when #getbyte is not available.
   class IO
+    # alias to #getc when #getbyte is not available
     alias_method :getbyte, :getc
   end
 
   # HighLine adds #getbyte alias to #getc when #getbyte is not available.
   class StringIO
+    # alias to #getc when #getbyte is not available
     alias_method :getbyte, :getc
   end
 end
@@ -15,6 +17,7 @@ end
 unless "".respond_to? :each_line
   # HighLine adds #each_line alias to #each when each_line is not available.
   class String
+    # alias to #each when each_line is not available.
     alias_method :each_line, :each
   end
 end
diff --git a/lib/highline/import.rb b/lib/highline/import.rb
index 017f41f..6f31de8 100644
--- a/lib/highline/import.rb
+++ b/lib/highline/import.rb
@@ -37,6 +37,9 @@ class Object
   # *Warning*:  This Object will be passed to String() before set.
   #
   # @param args [Array<#to_s>]
+  # @param details [lambda] block to be called with the question
+  #   instance as argument.
+  # @return [String] answer
   def or_ask( *args, &details )
     ask(*args) do |question|
       question.first_answer = String(self)
diff --git a/lib/highline/list.rb b/lib/highline/list.rb
index 48f8780..1f2af2c 100644
--- a/lib/highline/list.rb
+++ b/lib/highline/list.rb
@@ -108,11 +108,6 @@ class HighLine
       build
     end
 
-    # (see #list)
-    def to_a
-      list
-    end
-
     # Returns an Array representation of the list
     # in its current state.
     # @return [Array] @list.dup
@@ -120,6 +115,11 @@ class HighLine
       @list.dup
     end
 
+    # (see #list)
+    def to_a
+      list
+    end
+
     # Stringfies the list in its current state.
     # It joins each individual _cell_ with the current
     # {#row_join_string} between them.
diff --git a/lib/highline/question.rb b/lib/highline/question.rb
index 329e705..769da39 100755
--- a/lib/highline/question.rb
+++ b/lib/highline/question.rb
@@ -27,6 +27,10 @@ class HighLine
     # If _template_or_question_ is already a Question object just return it.
     # If not, build it.
     #
+    # @param template_or_question [String, Question] what to ask
+    # @param answer_type [Class] to what class to convert the answer
+    # @param details to be passed to Question.new
+    # @return [Question]
     def self.build(template_or_question, answer_type = nil, &details)
       if template_or_question.is_a? Question
         template_or_question
diff --git a/lib/highline/question/answer_converter.rb b/lib/highline/question/answer_converter.rb
index 6e24051..d4067f1 100644
--- a/lib/highline/question/answer_converter.rb
+++ b/lib/highline/question/answer_converter.rb
@@ -12,6 +12,11 @@ class HighLine
                      :answer, :answer=, :check_range,
                      :directory, :answer_type, :choices_complete
 
+      # It should be initialized with a Question object.
+      # The class will get the answer from {Question#answer}
+      # and then convert it to the proper {Question#answer_type}.
+      # It is mainly used by {Question#convert}
+      #
       # @param question [Question]
       def initialize(question)
         @question = question
diff --git a/lib/highline/simulate.rb b/lib/highline/simulate.rb
index 0f1049d..a39c1f1 100644
--- a/lib/highline/simulate.rb
+++ b/lib/highline/simulate.rb
@@ -17,6 +17,8 @@ class HighLine
   class Simulate
 
     # Creates a simulator with an array of Strings as a script
+    # @param strings [Array<String>] preloaded string to be used
+    #   as input buffer when simulating.
     def initialize(strings)
       @strings = strings
     end
@@ -41,7 +43,13 @@ class HighLine
       false
     end
 
-    # A wrapper method that temporarily replaces the Highline instance in $terminal with an instance of this object for the duration of the block
+    # A wrapper method that temporarily replaces the Highline
+    # instance in $terminal with an instance of this object
+    # for the duration of the block
+    #
+    # @param strings [String] preloaded string buffer that
+    #   will feed the input operations when simulating.
+
     def self.with(*strings)
       @input = $terminal.instance_variable_get :@input
       $terminal.instance_variable_set :@input, new(strings)
diff --git a/lib/highline/string_extensions.rb b/lib/highline/string_extensions.rb
index 1899e6b..d2f2de4 100644
--- a/lib/highline/string_extensions.rb
+++ b/lib/highline/string_extensions.rb
@@ -12,6 +12,7 @@ class HighLine
   # Included by HighLine::String.
   module StringExtensions
     # Included hook. Actions to take when being included.
+    # @param base [Class, Module] base class
     def self.included(base)
       define_builtin_style_methods(base)
       define_style_support_methods(base)
@@ -75,6 +76,7 @@ class HighLine
     end
 
     # At include time, it defines all basic builtin styles.
+    # @param base [Class, Module] base Class/Module
     def self.define_builtin_style_methods(base)
       HighLine::COLORS.each do |color|
         color = color.downcase