Improve HighLine::Terminal and childs documentation

3 files changed, 29 insertions, 5 deletions

diff --git a/lib/highline/terminal.rb b/lib/highline/terminal.rb
index 77020f5..ac06b3b 100755
--- a/lib/highline/terminal.rb
+++ b/lib/highline/terminal.rb
@@ -55,16 +55,18 @@ class HighLine
       @output = output
     end
 
-    # An initialization callback to be overloaded by other classes.
+    # An initialization callback.
     # It is called by {.get_terminal}.
     def initialize_system_extensions
     end
 
-    # @return [Array] two value terminal size
+    # @return [Array<Integer, Integer>] two value terminal
+    #   size like [columns, lines]
     def terminal_size
+      [80, 24]
     end
 
-    # Enter Raw No Echo mode. To be overloaded by other classes.
+    # Enter Raw No Echo mode.
     def raw_no_echo_mode
     end
 
@@ -82,6 +84,7 @@ class HighLine
     end
 
     # Get one character from the terminal
+    # @return [String] one character
     def get_character
     end
 
@@ -150,6 +153,8 @@ class HighLine
       highline.input.gets
     end
 
+    # @!group Enviroment queries
+
     # Running on JRuby?
     def jruby?
       defined?(RUBY_ENGINE) && RUBY_ENGINE == 'jruby'
@@ -165,6 +170,8 @@ class HighLine
       defined?(RUBY_PLATFORM) && (RUBY_PLATFORM =~ /mswin|mingw|cygwin/)
     end
 
+    # @!endgroup
+
     private
 
     # Yield a block using stty shell commands to preserve the terminal state.
diff --git a/lib/highline/terminal/io_console.rb b/lib/highline/terminal/io_console.rb
index c66f81e..b39e675 100644
--- a/lib/highline/terminal/io_console.rb
+++ b/lib/highline/terminal/io_console.rb
@@ -2,25 +2,34 @@
 
 class HighLine
   class Terminal
+    # io/console option for HighLine::Terminal.
+    # It's the most used terminal.
     class IOConsole < Terminal
+      # (see Terminal#terminal_size)
       def terminal_size
         output.winsize.reverse
       end
 
+      # Easy to query active terminal (character mode).
+      # For debugging purposes.
       CHARACTER_MODE = "io_console"   # For Debugging purposes only.
 
+      # (see Terminal#raw_no_echo_mode)
       def raw_no_echo_mode
         input.echo = false
       end
 
+      # (see Terminal#restore_mode)
       def restore_mode
         input.echo = true
       end
 
+      # (see Terminal#get_character)
       def get_character
         input.getch # from ruby io/console
       end
 
+      # Same as CHARACTER_MODE constant. "io_console"
       def character_mode
         "io_console"
       end
diff --git a/lib/highline/terminal/unix_stty.rb b/lib/highline/terminal/unix_stty.rb
index 4f567a6..46e87f4 100644
--- a/lib/highline/terminal/unix_stty.rb
+++ b/lib/highline/terminal/unix_stty.rb
@@ -2,10 +2,13 @@
 
 class HighLine
   class Terminal
+    # HighLine::Terminal option that uses external "stty" program
+    # to control terminal options.
     class UnixStty < Terminal
 
       # A Unix savvy method using stty to fetch the console columns, and rows.
       # ... stty does not work in JRuby
+      # @return (see Terminal#terminal_size)
       def terminal_size
         begin
           require "io/console"
@@ -24,23 +27,28 @@ class HighLine
         end
       end
 
-                                # *WARNING*:  This requires the external "stty" program!
-      CHARACTER_MODE = "unix_stty"   # For Debugging purposes only.
+      # Easy to query active terminal (character mode).
+      # For debugging purposes.
+      CHARACTER_MODE = "unix_stty"
 
+      # (see Terminal#raw_no_echo_mode)
       def raw_no_echo_mode
         @state = `stty -g`
         system "stty raw -echo -icanon isig"
       end
 
+      # (see Terminal#restore_mode)
       def restore_mode
         system "stty #{@state}"
         print "\r"
       end
 
+      # (see Terminal#get_character)
       def get_character( input = STDIN )
         input.getc
       end
 
+      # Same as CHARACTER_MODE constant. "unix_stty"
       def character_mode
         "unix_stty"
       end