Improve HighLine::ColorScheme documentation

1 files changed, 14 insertions, 5 deletions

diff --git a/lib/highline/color_scheme.rb b/lib/highline/color_scheme.rb
index c947531..11cd687 100644
--- a/lib/highline/color_scheme.rb
+++ b/lib/highline/color_scheme.rb
@@ -12,16 +12,14 @@
 class HighLine
   #
   # ColorScheme objects encapsulate a named set of colors to be used in the
-  # HighLine.colors() method call.  For example, by applying a ColorScheme that
+  # {HighLine.color} method call.  For example, by applying a ColorScheme that
   # has a <tt>:warning</tt> color then the following could be used:
   #
-  #   colors("This is a warning", :warning)
+  #   color("This is a warning", :warning)
   #
   # A ColorScheme contains named sets of HighLine color constants.
   #
-  # Example: Instantiating a color scheme, applying it to HighLine,
-  # and using it:
-  #
+  # @example Instantiating a color scheme, applying it to HighLine, and using it:
   #   ft = HighLine::ColorScheme.new do |cs|
   #          cs[:headline]        = [ :bold, :yellow, :on_black ]
   #          cs[:horizontal_line] = [ :bold, :white ]
@@ -50,6 +48,7 @@ class HighLine
     # converted to <tt>:symbols</tt> and values are converted to HighLine
     # constants.
     #
+    # @param h [Hash]
     def initialize( h = nil )
       @scheme = Hash.new
       load_from_hash(h) if h
@@ -57,6 +56,7 @@ class HighLine
     end
 
     # Load multiple colors from key/value pairs.
+    # @param h [Hash]
     def load_from_hash( h )
       h.each_pair do |color_tag, constants|
         self[color_tag] = constants
@@ -64,33 +64,42 @@ class HighLine
     end
 
     # Does this color scheme include the given tag name?
+    # @param color_tag [#to_sym]
+    # @return [Boolean]
     def include?( color_tag )
       @scheme.keys.include?(to_symbol(color_tag))
     end
 
     # Allow the scheme to be accessed like a Hash.
+    # @param color_tag [#to_sym]
+    # @return [Style]
     def []( color_tag )
       @scheme[to_symbol(color_tag)]
     end
 
     # Retrieve the original form of the scheme
+    # @param color_tag [#to_sym]
     def definition( color_tag )
       style = @scheme[to_symbol(color_tag)]
       style && style.list
     end
 
     # Retrieve the keys in the scheme
+    # @return [Array] of keys
     def keys
       @scheme.keys
     end
 
     # Allow the scheme to be set like a Hash.
+    # @param color_tag [#to_sym]
+    # @param constants [Array<Symbol>] Array of Style symbols
     def []=( color_tag, constants )
       @scheme[to_symbol(color_tag)] = HighLine::Style.new(:name=>color_tag.to_s.downcase.to_sym,
                                                           :list=>constants, :no_index=>true)
     end
 
     # Retrieve the color scheme hash (in original definition format)
+    # @return [Hash] scheme as Hash. It may be reused in a new ColorScheme.
     def to_hash
       @scheme.inject({}) { |hsh, pair| key, value = pair; hsh[key] = value.list; hsh }
     end