update docs of staff classes for YARD

Author: ievgrafov

lib/gnuplotrb/staff/datablock.rb

@@ -1,15 +1,13 @@
 module GnuplotRB
   ##
-  # === Overview
   # This class corresponds to points we want to plot. It may be
   # stored in temporary file (to allow fast update) or inside
   # "$DATA << EOD ... EOD" construction. Datablock stores data passed
   # to constructor and keeps datablock name or path to file where it is stored.
   class Datablock
     ##
-    # ====== Parameters
-    # * *data* - sequence of anything with +#to_gnuplot_points+ method.
-    # * *stored_in_file* true here will force this datablock to store its data
+    # @param data [#to_gnuplot_points] anything with #to_gnuplot_points method
+    # @param stored_in_file [Boolean] true here will force this datablock to store its data
     #   in temporary file.
     def initialize(data, stored_in_file = false)
       @stored_in_file = stored_in_file
@@ -25,12 +23,32 @@ def initialize(data, stored_in_file = false)
     end
 
     ##
-    # ====== Overview
     # Instantiate one more Datablock with updated data
     # if data stored in here-doc. Append update to file
     # if data stored there.
-    # ====== Parameters
-    # * *data* - anything with +#to_gnuplot_points+ method
+    #
+    # @param data [#to_gnuplot_points] anything with #to_gnuplot_points method
+    # @return [Datablock] self if data stored in file (see constructor)
+    # @return [Datablock] new datablock with updated data otherwise
+    #
+    # @example
+    #   data = [[0, 1, 2, 3], [0, 1, 4, 9]] # y = x**2
+    #   db = Datablock.new(data, false)
+    #   update = [[4, 5], [16, 25]]
+    #   updated_db = db.update(update)
+    #   # now db and updated_db contain DIFFERENT data
+    #   # db - points with x from 0 up to 3
+    #   # updated_db - points with x from 0 to 5
+    #
+    # @example
+    #   data = [[0, 1, 2, 3], [0, 1, 4, 9]] # y = x**2
+    #   db = Datablock.new(data, true)
+    #   update = [[4, 5], [16, 25]]
+    #   updated_db = db.update(update)
+    #   # now db and updated_db contain THE SAME data
+    #   # because they linked with the same temporary file
+    #   # db - points with x from 0 up to 5
+    #   # updated_db - points with x from 0 to 5
     def update(data)
       data_str = data.to_gnuplot_points
       if @stored_in_file
@@ -41,6 +59,19 @@ def update(data)
       end
     end
 
+    ##
+    # Update existing Datablock with new data.
+    # Destructive version of #update.
+    #
+    # @param data [#to_gnuplot_points] anything with #to_gnuplot_points method
+    # @return [Datablock] self
+    #
+    # @example
+    #   data = [[0, 1, 2, 3], [0, 1, 4, 9]] # y = x**2
+    #   db = Datablock.new(data, false)
+    #   update = [[4, 5], [16, 25]]
+    #   db.update!(update)
+    #   # now db contains points with x from 0 up to 5
     def update!(data)
       data_str = data.to_gnuplot_points
       if @stored_in_file
@@ -52,10 +83,12 @@ def update!(data)
     end
 
     ##
-    # ====== Overview
-    # Returns quoted filename if datablock stored in file or outputs
-    # datablock to gnuplot and returns its name otherwise.
-    # * *gnuplot_term* should be given if datablock not stored in file.
+    # Get quoted filename if datablock stored in file or output
+    # datablock to gnuplot and return its name otherwise.
+    # 
+    # @param gnuplot_term [Terminal] should be given if datablock not stored in file
+    # @return [String] quoted filename if data stored in file (see contructor)
+    # @return [String] Gnuplot's datablock name otherwise
     def name(gnuplot_term = nil)
       if @stored_in_file
         "'#{@file_name}'"
@@ -68,7 +101,6 @@ def name(gnuplot_term = nil)
     alias_method :to_s, :name
 
     ##
-    # ====== Overview
     # Overridden #clone. Since datablock which store data
     # in temporary files should not be cloned (otherwise it will cause
     # double attempt to delete file), this #clone returns self for such

lib/gnuplotrb/staff/dataset.rb

@@ -1,11 +1,10 @@
 module GnuplotRB
   ##
-  # === Overview
   # Dataset keeps control of Datablock or String (some math functions like
   # this 'x*sin(x)' or filename) and options related to original dataset
   # in gnuplot (with, title, using etc).
   #
-  # === Options
+  # == Options
   # Dataset options are explained in
   # {gnuplot docs}[http://www.gnuplot.info/docs_5.0/gnuplot.pdf](pp. 80-101).
   # Several common options:
@@ -28,6 +27,8 @@ class Dataset
     # Order is significant for some options
     OPTION_ORDER = %w(index using axes title)
 
+    private_constant :OPTION_ORDER
+
     ##
     # Hash of init handlers for data given in
     # different containers.
@@ -41,41 +42,39 @@ class Dataset
     ) if defined? Daru
 
     ##
-    # ====== Overview
-    # Creates new dataset out of given string with
-    # math function or filename. If *data* isn't a string
-    # it will create datablock to store data.
-    # ====== Parameters
-    # * *data* - String, Datablock or something acceptable by
-    #   Datablock.new as data (e.g. [x,y] where x and y are arrays)
-    # * *options* - hash of options specific for gnuplot
-    #   dataset, and some special options ('file: true' will
-    #   make data to be stored inside temporary file).
-    # ====== Examples
-    # Math function:
+    # Create new dataset out of given string with math function or filename.
+    # If *data* isn't a string it will create datablock to store data.
+    #
+    # @param data [String, Datablock, #to_gnuplot_points] String, Datablock or something acceptable
+    #   by Datablock.new as data (e.g. [x,y] where x and y are arrays)
+    # @param options [Hash] options specific for gnuplot
+    #   dataset (see Dataset top level doc), and some special options ('file: true' will
+    #   make data to be stored inside temporary file)
+    #
+    # @example Math function:
     #   Dataset.new('x*sin(x)', with: 'lines', lw: 4)
-    # File with points:
+    # @example File with points:
     #   Dataset.new('points.data', with: 'lines', title: 'Points from file')
-    # Some data (creates datablock stored in memory):
+    # @example Some data (creates datablock stored in memory):
     #   x = (0..5000).to_a
     #   y = x.map {|xx| xx*xx }
     #   points = [x, y]
     #   Dataset.new(points, with: 'points', title: 'Points')
-    # The same data but datablock stores it in temp file:
+    # @example The same data but datablock stores it in temp file:
     #   Dataset.new(points, with: 'points', title: 'Points', file: true)
     def initialize(data, **options)
       # run method by name
       send(INIT_HANDLERS[data.class], data, options)
     end
 
     ##
-    # ====== Overview
-    # Converts Dataset to string containing gnuplot dataset.
-    # ====== Parameters
-    # * *terminal* - must be given if data given as Datablock and
+    # Convert Dataset to string containing gnuplot dataset.
+    #
+    # @param terminal [Terminal] must be given if data given as Datablock and
     #   it does not use temp file so data should be piped out
-    #   to gnuplot via terminal before use.
-    # ====== Examples
+    #   to gnuplot via terminal before use
+    # @return [String] gnuplot dataset
+    # @example
     #   Dataset.new('points.data', with: 'lines', title: 'Points from file').to_s
     #   #=> "'points.data' with lines title 'Points form file'"
     #   Dataset.new(points, with: 'points', title: 'Points').to_s
@@ -85,26 +84,29 @@ def to_s(terminal = nil)
     end
 
     ##
-    # ====== Overview
-    # Creates new dataset with updated data (given
-    # data is appended to existing) and merged options.
+    # Create new dataset with updated data and merged options.
+    #
+    # Given data is appended to existing.
     # Data is updated only if Dataset stores it in Datablock.
     # Method does nothing if no options given and data isn't stored
     # in in-memory Datablock.
-    # ====== Parameters
-    # * *data* - data to append to existing
-    # * *options* - hash to merge with existing options
-    # ====== Examples
-    # Updating dataset with Math formula or filename given:
+    #
+    # @param data [#to_gnuplot_points] data to append to existing
+    # @param options [Hash] new options to merge with existing options
+    # @return self if dataset corresponds to math formula or file
+    #   (filename or temporary file if datablock)
+    # @return [Dataset] new dataset if data is stored in 'in-memory' Datablock
+    # @example Updating dataset with Math formula or filename given:
     #   dataset = Dataset.new('file.data')
     #   dataset.update(data: 'asd')
     #   #=> nothing updated
     #   dataset.update(data: 'asd', title: 'File')
     #   #=> Dataset.new('file.data', title: 'File')
-    # Updating dataset with data stored in Datablock:
+    # @example Updating dataset with data stored in Datablock (in-memory):
     #   in_memory_points = Dataset.new(points, title: 'Old one')
     #   in_memory_points.update(data: some_update, title: 'Updated')
     #   #=> Dataset.new(points + some_update, title: 'Updated')
+    # @example Updating dataset with data stored in Datablock (in-file):
     #   temp_file_points = Dataset.new(points, title: 'Old one', file: true)
     #   temp_file_points.update(data: some_update)
     #   #=> data updated but no new dataset created
@@ -123,14 +125,44 @@ def update(data = nil, **options)
       end
     end
 
+    ##
+    # Update Dataset with new data and options.
+    #
+    # Given data is appended to existing.
+    # Data is updated only if Dataset stores it in Datablock.
+    # Method does nothing if no options given and data isn't stored
+    # in in-memory Datablock.
+    #
+    # @param data [#to_gnuplot_points] data to append to existing
+    # @param options [Hash] new options to merge with existing options
+    # @return self
+    # @example Updating dataset with Math formula or filename given:
+    #   dataset = Dataset.new('file.data')
+    #   dataset.update!(data: 'asd')
+    #   #=> nothing updated
+    #   dataset.update!(data: 'asd', title: 'File')
+    #   dataset.title
+    #   #=> 'File' # data isn't updated
+    # @example Updating dataset with data stored in Datablock (in-memory):
+    #   in_memory_points = Dataset.new(points, title: 'Old one')
+    #   in_memory_points.update!(data: some_update, title: 'Updated')
+    #   in_memory_points.data
+    #   #=> points + some_update
+    #   in_memory_points.title
+    #   #=> 'Updated'
+    # @example Updating dataset with data stored in Datablock (in-file):
+    #   temp_file_points = Dataset.new(points, title: 'Old one', file: true)
+    #   temp_file_points.update!(data: some_update)
+    #   #=> data updated but no new dataset created
+    #   temp_file_points.update!(data: some_update, title: 'Updated')
+    #   #=> data and options updated
     def update!(data = nil, **options)
       @data.update!(data) if data
       options!(options)
       self
     end
 
     ##
-    # ====== Overview
     # Own implementation of #clone. Creates new Dataset if
     # data stored in datablock and calls super otherwise.
     def clone
@@ -142,11 +174,13 @@ def clone
     end
 
     ##
-    # ====== Overview
-    # Creates new Plot object with only one Dataset given - self.
+    # Create new Plot object with only one Dataset given - self.
     # Calls #plot on created Plot. All arguments given to this #plot
     # will be sent to Plot#plot instead.
-    # ====== Example
+    # @param args sequence of arguments all of which will be passed to Plot#plot,
+    #   see docs there
+    # @return [Plot] new Plot object with only one Dataset - self
+    # @example
     #   sin = Dataset.new('sin(x)')
     #   sin.plot(term: [qt, size: [300, 300]])
     #   #=> shows qt window 300x300 with sin(x)
@@ -159,13 +193,13 @@ def plot(*args)
     private
 
     ##
-    # ====== Overview
-    # Creates new dataset with existing options merged with
+    # Create new dataset with existing options merged with
     # the given ones. Does nothing if no options given.
-    # ====== Parameters
-    # * *options* - hash to merge with existing options
-    # ====== Examples
-    # Updating dataset with Math formula or filename given:
+    #
+    # @param options [Hash] new options to merge with existing options
+    # @return [Dataset] self if options empty
+    # @return [Dataset] new Dataset with updated options otherwise
+    # @example Updating dataset with Math formula or filename given:
     #   dataset = Dataset.new('file.data')
     #   dataset.update_options(title: 'File')
     #   #=> Dataset.new('file.data', title: 'File')
@@ -178,32 +212,37 @@ def update_options(**options)
     end
 
     ##
-    # ====== Overview
     # Create string from own options
+    # @return [String] options converted to Gnuplot format
     def options_to_string
       options.sort_by { |key, _| OPTION_ORDER.find_index(key.to_s) || 999 }
              .map { |key, value| OptionHandling.option_to_string(key, value) }
              .join(' ')
     end
 
     ##
-    # Needed by OptionHandling to create new object when
-    # options are changed.
+    # Needed by OptionHandling to create new object when options are changed.
     def new_with_options(options)
       self.class.new(@data, options)
     end
 
+    ##
+    # Initialize Dataset from given String
     def init_string(data, options)
       @type, @data = File.exist?(data) ? [:datafile, "'#{data}'"] : [:math_function, data.clone]
       @options = Hamster.hash(options)
     end
 
+    ##
+    # Initialize Dataset from given Datablock
     def init_dblock(data, options)
       @type = :datablock
       @data = data.clone
       @options = Hamster.hash(options)
     end
 
+    ##
+    # Create new value for 'using' option based on column count
     def get_daru_columns(data, cnt)
       new_opt = (2..cnt).to_a.join(':')
       if data.index[0].is_a?(DateTime) || data.index[0].is_a?(Numeric)
@@ -213,6 +252,8 @@ def get_daru_columns(data, cnt)
       end
     end
 
+    ##
+    # Initialize Dataset from given Daru::DataFrame
     def init_daru_frame(data, options)
       options[:title] ||= data.name
       if options[:using]
@@ -229,12 +270,16 @@ def init_daru_frame(data, options)
       init_default(data, options)
     end
 
+    ##
+    # Initialize Dataset from given Daru::Vector
     def init_daru_vector(data, options)
       options[:using] ||= get_daru_columns(data, 2)
       options[:title] ||= data.name
       init_default(data, options)
     end
 
+    ##
+    # Initialize Dataset from given data with #to_gnuplot_points method
     def init_default(data, file: false, **options)
       @type = :datablock
       @data = Datablock.new(data, file)