gnuplotrb 0.3.0 → 0.3.1

data/lib/gnuplotrb/plot.rb

@@ -1,19 +1,50 @@
 module GnuplotRB
   ##
-  # === Overview
-  # Plot correspond to simple 2D visualisation
+  # Class corresponding to simple 2D visualisation.
+  #
+  # == Notebooks
+  #
+  # * {Heatmaps}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/heatmaps.ipynb]
+  # * {Vector field}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/vector_field.ipynb]
+  # * {Math equations}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/math_plots.ipynb]
+  # * {Histogram}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/histogram.ipynb]
+  # * {Updating plots with new data}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/updating_data.ipynb]
+  #
+  # == Options
+  # All possible options are exaplained in 
+  # {gnuplot docs}[http://www.gnuplot.info/docs_5.0/gnuplot.pdf] (pp. 105-190).
+  #
+  # Several common ones:
+  #
+  # * xrange(yrange, zrange, urange, vrange) - set range for a variable. Takes
+  #   Range (xrange: 0..100), or String (yrange: '[0:100]').
+  # * title - plot's title. Takes String (title: 'Some new plot').
+  # * polar (parametric) - plot in polar or parametric space. Takes boolean (true).
+  # * style_data - set style for plotting data. Takes string, possible values: histogram,
+  #   points, lines, linespoints, boxes etc. See gnuplot docs for more.
+  # * term - select terminal used by gnuplot. Examples: { term: 'png' },
+  #   { term: ['svg', size: [600, 600]] }. Deprecated due to existance of #to_<term_name> methods.
+  #   One can use #to_png and #to_svg(size: [600, 600]) instead of passing previous options.
+  # * output - select filename to output plot to. Should be used together with term. Deprecated
+  #   due to existance of #to_<term_name> methods. One should use #to_png('file.png') instead of
+  #   passing { term: 'png', output: 'file.png' }.
+  # Every option may be passed to constructor in order to create plot with it.
+  #
+  # Methods #options(several: options, ...) and bunch of #option_name(only_an: option) such as
+  # #xrange, #using, #polar etc create new Plot object based on existing but with a new options.
+  #
+  # Methods with the same names ending with '!' or '=' ('plot.xrange!(1..3)',
+  # 'plot.title = "New title"') are destructive and modify state of existing object just as
+  # "Array#sort!" do with Array object. See notebooks for examples.
   class Plot
     include Plottable
     ##
     # Array of datasets which are plotted by this object.
     attr_reader :datasets
     ##
-    # ====== Arguments
-    # * *datasets* are either instances of Dataset class or
-    #   [data, **dataset_options] arrays from which Dataset may be created
-    # * *options* will be considered as 'settable' options of gnuplot
-    #   ('set xrange [1:10]' for { xrange: 1..10 },
-    #   "set title 'plot'" for { title: 'plot' } etc)
+    # @param *datasets [Sequence of Dataset or Array] either instances of Dataset class or
+    #   "[data, **dataset_options]"" arrays
+    # @param options [Hash] see Plot top level doc for options examples
     def initialize(*datasets)
       # had to relace **options arg with this because in some cases
       # Daru::DataFrame was mentioned as hash and added to options
@@ -30,14 +61,13 @@ module GnuplotRB
     end
 
     ##
-    # ====== Overview
-    # This outputs plot to term (if given) or to this plot's own terminal.
-    # ====== Arguments
-    # * *term* - Terminal to plot to
-    # * *multiplot_part* - part of a multiplot. Option for inner usage
-    # * *options* - will be considered as 'settable' options of gnuplot
-    #   ('set xrange [1:10]', 'set title 'plot'' etc)
-    # Options passed here have priority over already existing.
+    # Output plot to term (if given) or to this plot's own terminal.
+    #
+    # @param term [Terminal] Terminal object to plot to
+    # @param :multiplot_part [Boolean] true if this plot is part of a multiplot. For inner use!
+    # @param options [Hash] see options in Plot top level doc.
+    #   Options passed here have priority over already existing.
+    # @return [Plot] self
     def plot(term = nil, multiplot_part: false, **options)
       fail ArgumentError, 'Empty plots are not supported!' if @datasets.empty?
       inner_opts = if multiplot_part
@@ -62,16 +92,17 @@ module GnuplotRB
     alias_method :replot, :plot
 
     ##
-    # ====== Overview
     # Create new Plot object where dataset at *position* will
     # be replaced with the new one created from it by updating.
-    # ====== Arguments
-    # * *position* - position of dataset which you need to update
+    #
+    # @param position [Integer] position of dataset which you need to update
     #   (by default first dataset is updated)
-    # * *data* - data to update dataset with
-    # * *options* - options to update dataset with
-    # ====== Example
+    # @param data [#to_gnuplot_points] data to update dataset with
+    # @param options [Hash] options to update dataset with, see Dataset top level doc
+    #
+    # @example
     #   updated_plot = plot.update_dataset(data: [x1,y1], title: 'After update')
+    #   # plot IS NOT affected (if dataset did not store data in a file)
     def update_dataset(position = 0, data: nil, **options)
       old_ds = @datasets[position]
       new_ds = old_ds.update(data, options)
@@ -79,37 +110,74 @@ module GnuplotRB
     end
 
     ##
-    # ====== Overview
+    # Updates existing Plot object by replacing dataset at *position*
+    # with the new one created from it by updating.
+    #
+    # @param position [Integer] position of dataset which you need to update
+    #   (by default first dataset is updated)
+    # @param data [#to_gnuplot_points] data to update dataset with
+    # @param options [Hash] options to update dataset with, see Dataset top level doc
+    #
+    # @example
+    #   plot.update_dataset!(data: [x1,y1], title: 'After update')
+    #   # plot IS affected anyway
+    def update_dataset!(position = 0, data: nil, **options)
+      @datasets[position].update!(data, options)
+      self
+    end
+
+    ##
     # Create new Plot object where dataset at *position* will
     # be replaced with the given one.
-    # ====== Arguments
-    # * *position* - position of dataset which you need to update
+    #
+    # @param position [Integer] position of dataset which you need to replace
     #   (by default first dataset is replaced)
-    # * *dataset* - dataset to replace the old one. You can also
-    #   give here [data, **dataset_options] array from
-    #   which Dataset may be created.
-    # ====== Example
+    # @param dataset [Dataset, Array] dataset to replace the old one. You can also
+    #   give here "[data, **dataset_options]"" array from which Dataset may be created.
+    # @example
     #   sinx = Plot.new('sin(x)')
     #   cosx = sinx.replace_dataset(['cos(x)'])
+    #   # sinx IS NOT affected
     def replace_dataset(position = 0, dataset)
       self.class.new(@datasets.set(position, dataset_from_any(dataset)), @options)
     end
 
     ##
-    # ====== Overview
+    # Updates existing Plot object by replacing dataset at *position*
+    # with the given one.
+    #
+    # @param position [Integer] position of dataset which you need to replace
+    #   (by default first dataset is replaced)
+    # @param dataset [Dataset, Array] dataset to replace the old one. You can also
+    #   give here "[data, **dataset_options]"" array from which Dataset may be created.
+    # @example
+    #   sinx = Plot.new('sin(x)')
+    #   sinx.replace_dataset!(['cos(x)'])
+    #   # sinx IS affected
+    def replace_dataset!(position = 0, dataset)
+      @datasets = @datasets.set(position, dataset_from_any(dataset))
+      self
+    end
+
+    alias_method :[]=, :replace_dataset!
+
+    ##
     # Create new Plot object where given datasets will
     # be inserted into dataset list before given position
     # (position = 0 by default).
-    # ====== Arguments
-    # * *position* - position where to insert given datasets
-    # * *datasets* - sequence of datasets to add
-    # ====== Example
+    #
+    # @param position [Integer] position of dataset BEFORE which datasets will be placed.
+    #   0 by default.
+    # @param *datasets [ Sequence of Dataset or Array] datasets to insert
+    # @example
     #   sinx = Plot.new('sin(x)')
     #   sinx_and_cosx_with_expx = sinx.add(['cos(x)'], ['exp(x)'])
     #
     #   cosx_and_sinx = sinx << ['cos(x)']
+    #   # sinx IS NOT affected in both cases
     def add_datasets(*datasets)
       datasets.map! { |ds| ds.is_a?(Numeric) ? ds : dataset_from_any(ds) }
+      # first element is position where to add datasets
       datasets.unshift(0) unless datasets[0].is_a?(Numeric)
       self.class.new(@datasets.insert(*datasets), @options)
     end
@@ -118,23 +186,58 @@ module GnuplotRB
     alias_method :<<, :add_datasets
 
     ##
-    # ====== Overview
+    # Updates existing Plot object by inserting given datasets
+    # into dataset list before given position (position = 0 by default).
+    #
+    # @param position [Integer] position of dataset BEFORE which datasets will be placed.
+    #   0 by default.
+    # @param *datasets [ Sequence of Dataset or Array] datasets to insert
+    # @example
+    #   sinx = Plot.new('sin(x)')
+    #   sinx.add!(['cos(x)'], ['exp(x)'])
+    #   # sinx IS affected
+    def add_datasets!(*datasets)
+      datasets.map! { |ds| ds.is_a?(Numeric) ? ds : dataset_from_any(ds) }
+      # first element is position where to add datasets
+      datasets.unshift(0) unless datasets[0].is_a?(Numeric)
+      @datasets = @datasets.insert(*datasets)
+      self
+    end
+
+    alias_method :add_dataset!, :add_datasets!
+
+    ##
     # Create new Plot object where dataset at given position
     # will be removed from dataset list.
-    # ====== Arguments
-    # * *position* - position of dataset that should be
+    #
+    # @param position [Integer] position of dataset that should be
     #   removed (by default last dataset is removed)
-    # ====== Example
+    # @example
     #   sinx_and_cosx = Plot.new('sin(x)', 'cos(x)')
     #   sinx = sinx_and_cosx.remove_dataset
     #   cosx = sinx_and_cosx.remove_dataset(0)
+    #   # sinx_and_cosx IS NOT affected in both cases
     def remove_dataset(position = -1)
       self.class.new(@datasets.delete_at(position), @options)
     end
 
     ##
-    # ====== Overview
-    # The same as Plot#datasets[args]
+    # Updates existing Plot object by removing dataset at given position.
+    #
+    # @param position [Integer] position of dataset that should be
+    #   removed (by default last dataset is removed)
+    # @example
+    #   sinx_and_cosx = Plot.new('sin(x)', 'cos(x)')
+    #   sinx_and_cosx!.remove_dataset
+    #   sinx_and_cosx!.remove_dataset
+    #   # sinx_and_cosx IS affected and now is empty
+    def remove_dataset!(position = -1)
+      @datasets = @datasets.delete_at(position)
+      self
+    end
+
+    ##
+    # The same as #datasets[*args]
     def [](*args)
       @datasets[*args]
     end
@@ -149,11 +252,11 @@ module GnuplotRB
       return unless data.is_a?(Daru::DataFrame) || data.is_a?(Daru::Vector)
       return unless data.index.first.is_a?(DateTime)
       return if using[0..1] != '1:'
-      @options = @options.merge(
+      @options = Hamster::Hash.new(
         xdata: 'time',
         timefmt: '%Y-%m-%dT%H:%M:%S',
         format_x: '%d\n%b\n%Y'
-      )
+      ).merge(@options)
     end
 
     ##

data/lib/gnuplotrb/splot.rb

@@ -1,15 +1,15 @@
 module GnuplotRB
   ##
-  # === Overview
-  # Splot class correspond to simple 3D visualisation
+  # Splot class correspond to simple 3D visualisation.
+  # Most of Plot's docs are right for Splot too.
+  #
+  # Examples of usage are in
+  # {a notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/3d_plot.ipynb]
   class Splot < Plot
     ##
-    # ==== Arguments
-    # * *datasets* are either instances of Dataset class or
-    #   [data, **dataset_options] arrays
-    # * *options* will be considered as 'settable' options of gnuplot
-    #   ('set xrange [1:10]' for { xrange: 1..10 }, "set title 'plot'"
-    #   for { title: 'plot' } etc)
+    # @param *datasets [Sequence of Dataset or Array] either instances of Dataset class or
+    #   "[data, **dataset_options]"" arrays
+    # @param options [Hash] see Plot top level doc for options examples
     def initialize(*datasets, **options)
       super
       @cmd = 'splot '

data/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 @@ module GnuplotRB
     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
@@ -42,10 +60,35 @@ module GnuplotRB
     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.
+    # 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
+        File.open(@file_name, 'a') { |f| f.puts "\n#{data_str}" }
+      else
+        @data = "#{@data}\n#{data_str}"
+      end
+      self
+    end
+
+    ##
+    # 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}'"
@@ -58,7 +101,6 @@ module GnuplotRB
     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

data/lib/gnuplotrb/staff/dataset.rb

@@ -1,9 +1,22 @@
 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
+  # Dataset options are explained in
+  # {gnuplot docs}[http://www.gnuplot.info/docs_5.0/gnuplot.pdf] (pp. 80-101).
+  # Several common options:
+  # * with - set plot style for dataset ('lines', 'points', 'impulses' etc)  
+  # * using - choose which columns of input data gnuplot should use. Takes String
+  #   (using: 'xtic(1):2:3'). If Daru::Dataframe passed one can use column names
+  #   instead of numbers (using: 'index:value1:summ' - value1 and summ here are column names).
+  # * linewidth (lw) - integer line width
+  # * dashtype (dt) - takes pattern with dash style. Examples: '.. ', '-- ', '.-  '.
+  # * pointtype (pt) - takes integer number of point type (works only when :with option is set to
+  #   'points'). One can call Terminal::test(term_name)
+  #   or Terminal#test in order to see which point types are supported by terminal.
   class Dataset
     include Plottable
     ##
@@ -14,6 +27,8 @@ module GnuplotRB
     # 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.
@@ -27,27 +42,25 @@ module GnuplotRB
     ) 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
@@ -55,42 +68,49 @@ module GnuplotRB
     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
+    # @param :without_options [Boolean] do not add options to dataset if set
+    #   to true. Used by Fit::fit
+    # @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'"
+    #   #=> "'points.data' with lines title 'Points from file'"
     #   Dataset.new(points, with: 'points', title: 'Points').to_s
     #   #=> "$DATA1 with points title 'Points'"
-    def to_s(terminal = nil)
-      "#{@type == :datablock ? @data.name(terminal) : @data} #{options_to_string}"
+    def to_s(terminal = nil, without_options: false)
+      result = "#{@type == :datablock ? @data.name(terminal) : @data} "
+      result += options_to_string unless without_options
+      result
     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
@@ -110,7 +130,43 @@ module GnuplotRB
     end
 
     ##
-    # ====== Overview
+    # 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
+
+    ##
     # Own implementation of #clone. Creates new Dataset if
     # data stored in datablock and calls super otherwise.
     def clone
@@ -122,11 +178,13 @@ module GnuplotRB
     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)
@@ -139,13 +197,13 @@ module GnuplotRB
     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')
@@ -158,8 +216,8 @@ module GnuplotRB
     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) }
@@ -167,23 +225,28 @@ module GnuplotRB
     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)
@@ -193,6 +256,8 @@ module GnuplotRB
       end
     end
 
+    ##
+    # Initialize Dataset from given Daru::DataFrame
     def init_daru_frame(data, options)
       options[:title] ||= data.name
       if options[:using]
@@ -202,19 +267,24 @@ module GnuplotRB
             "#{Regexp.last_match(1)}#{array_index + 2}#{Regexp.last_match(2)}"
           end
         end
-        options[:using].gsub!('index', '1').strip!
+        options[:using].gsub!('index', '1')
+        options[:using].strip!
       else
         options[:using] = get_daru_columns(data, data.vectors.size + 1)
       end
       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)