update mixins doc for YARD

Author: ievgrafov

lib/gnuplotrb/mixins/error_handling.rb

@@ -9,7 +9,6 @@ class GnuplotError < ArgumentError
   # handle errors from its stderr.
   module ErrorHandling
     ##
-    # ====== Overview
     # Check if there were errors in previous commands.
     # Throws GnuplotError in case of any errors.
     def check_errors
@@ -28,7 +27,6 @@ def check_errors
     private
 
     ##
-    # ====== Overview
     # Start new thread that will read stderr given as stream
     # and add errors into @err_array.
     def handle_stderr(stream)

lib/gnuplotrb/mixins/option_handling.rb

@@ -1,13 +1,12 @@
 module GnuplotRB
   ##
-  # ====== Overview
   # This module contains methods which are mixed into several classes
   # to set, get and convert their options.
   module OptionHandling
     class << self
-      # Some values of options should be quoted to be read by gnuplot
+      # Some values of options should be quoted to be read by gnuplot properly
       #
-      # TODO: update list with data from gnuplot documentation !!!
+      # @todo update list with data from gnuplot documentation !!!
       QUOTED_OPTIONS = %w(
         title
         output
@@ -34,24 +33,29 @@ class << self
         dashtype
       )
 
+      private_constant :QUOTED_OPTIONS
+
       ##
-      # Replacement '_' with ' ' is made to allow passing several options
-      # with the same first word of key.
-      # See issue #7 for more info.
+      # Replace '_' with ' ' is made to allow passing several options
+      # with the same first word of key. See issue #7 for more info.
+      # @param key [Symbol, String] key to modify
+      # @return [String] given key with '_' replaced with ' '
       def string_key(key)
         key.to_s.gsub(/_/) { ' ' } + ' '
       end
 
       ##
-      # ====== Overview
       # Recursive function that converts Ruby option to gnuplot string
-      # ====== Arguments
-      # * *key* - name of option in gnuplot
-      # * *option* - an option that should be converted
-      # ====== Examples
-      #   option_to_string(['png', size: [300, 300]]) #=> 'png size 300,300'
-      #   option_to_string(xrange: 0..100) #=> 'xrange [0:100]'
-      #   option_to_string(multiplot: true) #=> 'multiplot'
+      #
+      # @param key [Symbol] name of option in gnuplot
+      # @param option an option that should be converted
+      # @example
+      #   option_to_string(['png', size: [300, 300]])
+      #   #=> 'png size 300,300'
+      #   option_to_string(xrange: 0..100)
+      #   #=> 'xrange [0:100]'
+      #   option_to_string(multiplot: true)
+      #   #=> 'multiplot'
       def option_to_string(key = nil, option)
         return string_key(key) if !!option == option # check for boolean
         value = ruby_class_to_gnuplot(option)
@@ -62,6 +66,7 @@ def option_to_string(key = nil, option)
       end
 
       ##
+      # @private
       # Method for inner use.
       # Needed to convert several ruby classes into
       # value that should be piped to gnuplot.
@@ -81,23 +86,20 @@ def ruby_class_to_gnuplot(option_object)
       end
 
       ##
-      # ====== Overview
       # Check if given terminal available for use.
-      # ====== Arguments
-      # * *terminal* - terminal to check (e.g. 'png', 'qt', 'gif')
+      #
+      # @param terminal [String] terminal to check (e.g. 'png', 'qt', 'gif')
+      # @return [Boolean] true or false
       def valid_terminal?(terminal)
         Settings.available_terminals.include?(terminal)
       end
 
       ##
-      # ====== Overview
       # Check if given options are valid for gnuplot.
       # Raises ArgumentError if invalid options found.
-      # ====== Arguments
-      # * *options* - Hash of options to check
-      #   (e.g. {term: 'qt', title: 'Plot title'})
-      #
       # Now checks only terminal name.
+      #
+      # @param options [Hash] options to check (e.g. "{ term: 'qt', title: 'Plot title' }")
       def validate_terminal_options(options)
         terminal = options[:term]
         return unless terminal
@@ -110,34 +112,35 @@ def validate_terminal_options(options)
     end
 
     ##
+    # @private
     # You should implement #initialize in classes that use OptionsHelper
     def initialize(*_)
       fail NotImplementedError, 'You should implement #initialize' \
                                 ' in classes that use OptionsHelper!'
     end
 
     ##
+    # @private
     # You should implement #new_with_options in classes that use OptionsHelper
     def new_with_options(*_)
       fail NotImplementedError, 'You should implement #new_with_options' \
                                 ' in classes that use OptionsHelper!'
     end
 
     ##
-    # ====== Overview
     # Create new Plot (or Dataset or Splot or Multiplot) object where current
     # options are merged with given. If no options
     # given it will just return existing set of options.
-    # ====== Arguments
-    # * *options* - options to add. If no options given, current
-    #   options are returned.
-    # ====== Example
+    #
+    # @param options [Hash] options to add
+    # @return [Dataset, Splot, Multiplot] new object created with given options
+    # @return [Hamster::Hash] current options if given options empty
+    # @example
     #   sin_graph = Plot.new(['sin(x)', title: 'Sin'], title: 'Sin on [0:3]', xrange: 0..3)
     #   sin_graph.plot
     #   sin_graph_update = sin_graph.options(title: 'Sin on [-10:10]', xrange: -10..10)
     #   sin_graph_update.plot
-    #   # this may also be considered as
-    #   # sin_graph.title(...).xrange(...)
+    #   # sin_graph IS NOT affected
     def options(**options)
       @options ||= Hamster::Hash.new
       if options.empty?
@@ -148,7 +151,16 @@ def options(**options)
     end
 
     ##
-    # Destructive twin of #options
+    # Update existing Plot (or Dataset or Splot or Multiplot) object with given options.
+    #
+    # @param options [Hash] options to add
+    # @return [Dataset, Splot, Multiplot] self
+    # @example
+    #   sin_graph = Plot.new(['sin(x)', title: 'Sin'], title: 'Sin on [0:3]', xrange: 0..3)
+    #   sin_graph.plot
+    #   sin_graph.options!(title: 'Sin on [-10:10]', xrange: -10..10)
+    #   sin_graph.plot
+    #   # second #plot call will plot not the same as first, sin_graph IS affected
     def options!(**options)
       @options = @options ? @options.merge(options) : Hamster::Hash.new(options)
       self
@@ -157,9 +169,8 @@ def options!(**options)
     private
 
     ##
-    # ====== Arguments
-    # * *key* - [Symbol] - option key
-    # * *value* - anything treated as options value in gnuplot gem
+    # Return current option value if no value given. Create new
+    # object with given option set if value given.
     def option(key, *value)
       if value.empty?
         value = options[key]
@@ -170,6 +181,8 @@ def option(key, *value)
       end
     end
 
+    ##
+    # Just set an option.
     def option!(key, *value)
       options!(key => value)
     end

lib/gnuplotrb/mixins/plottable.rb

@@ -7,39 +7,39 @@ module Plottable
     include OptionHandling
 
     ##
+    # @private
     # You should implement #plot in classes that are Plottable
     def plot(*_)
       fail NotImplementedError, 'You should implement #plot in classes that are Plottable!'
     end
 
     ##
-    # ====== Overview
     # In this gem #method_missing is used both to handle
     # options and to handle plotting to specific terminal.
     #
-    # ====== Options handling
-    # ======= Overview
+    # == Options handling
+    # === Overview
     # You may set options using #option_name(option_value) method.
     # A new object will be constructed with selected option set.
     # And finally you can get current value of any option using
     # #options_name without arguments.
-    # ======= Arguments
+    # === Arguments
     # * *option_value* - value to set an option. If none given
     #   method will just return current option's value
-    # ======= Examples
+    # === Examples
     #   plot = Splot.new
     #   new_plot = plot.title('Awesome plot')
     #   plot.title #=> nil
     #   new_plot.title #=> 'Awesome plot'
     #
-    # ====== Plotting to specific term
-    # ======= Overview
+    # == Plotting to specific term
+    # === Overview
     # Gnuplot offers possibility to output graphics to many image formats.
     # The easiest way to to so is to use #to_<plot_name> methods.
-    # ======= Arguments
+    # === Arguments
     # * *options* - set of options related to terminal (size, font etc).
     #   Be careful, some terminals have their own specific options.
-    # ======= Examples
+    # === Examples
     #   # font options specific for png term
     #   multiplot.to_png('./result.png', size: [300, 500], font: ['arial', 12])
     #   # font options specific for svg term
@@ -62,8 +62,9 @@ def method_missing(meth_id, *args)
     end
 
     ##
-    # Returns true foe existing methods and
-    # #to_<term_name> when name is a valid terminal type.
+    # @return [true] for existing methods and
+    #   #to_|term_name| when name is a valid terminal type.
+    # @return [false] otherwise
     def respond_to?(meth_id)
       # Next line is here to force iRuby use #to_iruby
       # instead of #to_svg.
@@ -74,8 +75,7 @@ def respond_to?(meth_id)
     end
 
     ##
-    # This method is used to embed plottable objects
-    # into iRuby notebooks. There is
+    # This method is used to embed plottable objects into iRuby notebooks. There is
     # {a notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/basic_usage.ipynb]
     # with examples of its usage.
     def to_iruby
@@ -92,20 +92,16 @@ def to_iruby
     end
 
     ##
-    # :call-seq:
-    # to_png('file.png') -> creates file with plot
-    # to_svg -> svg file contents
-    # to_canvas('plot.html', size: [300,300]) -> creates file with plot
-    #
-    # ====== Overview
-    # Method which outputs plot to specific terminal (possibly some file).
+    # @private
+    # Output plot to specific terminal (possibly some file).
     # Explicit use should be avoided. This method is called from #method_missing
     # when it handles method names like #to_png(options).
-    # ====== Arguments
-    # * *path* - path to output file, if none given it will output to temp file
+    #
+    # @param trminal [String] terminal name ('png', 'svg' etc)
+    # @param path [String] path to output file, if none given it will output to temp file
     #   and then read it and return binary contents of file
-    # * *options* - used in #plot
-    # ====== Examples
+    # @param options [Hash] used in #plot
+    # @example
     #   ## plot here may be Plot, Splot, Multiplot or any other plottable class
     #   plot.to_png('./result.png', size: [300, 500])
     #   contents = plot.to_svg(size: [100, 100])
@@ -123,9 +119,90 @@ def to_specific_term(terminal, path = nil, **options)
     end
 
     ##
-    # Returns terminal object linked with this Plottable object.
+    # @return [Terminal] terminal object linked with this Plottable object
     def own_terminal
       @terminal ||= Terminal.new
     end
+
+    ##
+    # @!method xrange(value = nil)
+    # @!method yrange(value = nil)
+    # @!method title(value = nil)
+    # @!method option_name(value = nil)
+    # Clone existing object and set new options value in created one or just return
+    # existing value if nil given.
+    #
+    # Method is handled by #method_missing.
+    #
+    # You may set options using #option_name(option_value) method.
+    # A new object will be constructed with selected option set.
+    # And finally you can get current value of any option using
+    # #options_name without arguments.
+    # 
+    # Available options are listed in Plot, Splot, Multiplot etc class top level doc.
+    #
+    # @param value new value for option
+    # @return new object with option_name set to *value* if value given
+    # @return old option value if no value given
+    #
+    # @example
+    #   plot = Splot.new
+    #   new_plot = plot.title('Awesome plot')
+    #   plot.title #=> nil
+    #   new_plot.title #=> 'Awesome plot'
+
+    ##
+    # @!method xrange!(value)
+    # @!method yrange!(value)
+    # @!method title!(value)
+    # @!method option_name!(value)
+    # Set value for an option.
+    #
+    # Method is handled by #method_missing.
+    #
+    # You may set options using obj.option_name!(option_value) or 
+    # obj.option_name = option_value methods.
+    # 
+    # Available options are listed in Plot, Splot, Multiplot etc class top level doc.
+    #
+    # @param value new value for option
+    # @return self
+    #
+    # @example
+    #   plot = Splot.new
+    #   plot.title #=> nil
+    #   plot.title!('Awesome plot')
+    #   plot.title #=> 'Awesome plot'
+    #
+    # @example
+    #   plot = Splot.new
+    #   plot.title #=> nil
+    #   plot.title = 'Awesome plot'
+    #   plot.title #=> 'Awesome plot'
+
+    ##
+    # @!method to_png(path = nil, **options)
+    # @!method to_svg(path = nil, **options)
+    # @!method to_gif(path = nil, **options)
+    # @!method to_canvas(path = nil, **options)
+    # Output to plot to according image format.
+    #
+    # All of #to_|terminal_name| methods are handled with #method_missing.
+    #
+    # Gnuplot offers possibility to output graphics to many image formats.
+    # The easiest way to to so is to use #to_<plot_name> methods.
+    #
+    # @param path [String] path to save plot file to.
+    # @param options [Hash] specific terminal options like 'size',
+    #   'font' etc
+    #
+    # @return [String] contents of plotted file unless path given
+    # @return self if path given
+    #
+    # @example
+    #   # font options specific for png term
+    #   multiplot.to_png('./result.png', size: [300, 500], font: ['arial', 12])
+    #   # font options specific for svg term
+    #   content = multiplot.to_svg(size: [100, 100], fname: 'Arial', fsize: 12)
   end
 end