update Fit docs for YARD

Author: ievgrafov

lib/gnuplotrb/fit.rb

@@ -1,32 +1,36 @@
 module GnuplotRB
   ##
-  # Contains methods relating to Gnuplot's fit function.
+  # Contains methods relating to Gnuplot's fit function. Covered in
+  # {fit notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/fitting_data.ipynb].
+  #
+  # You can also see original gnuplot's fit in gnuplot
+  # doc - http://www.gnuplot.info/docs_5.0/gnuplot.pdf p. 122.
   module Fit
     ##
-    # ====== Overview
-    # Fit given data with function. Covered in
-    # {fit notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/fitting_data.ipynb].
-    # ====== Arguments
-    # * *data* - method accepts the same sources as Dataset.new
+    # Fit given data with function.
+    #
+    # Fit waits for output from gnuplot Settings.max_fit_delay and throw exception if gets nothing.
+    # One can change this value in order to wait longer (if huge datasets is fitted).
+    #
+    # @param data [#to_gnuplot_points] method accepts the same sources as Dataset.new
     #   and Dataset object
-    # * *:function* - function to fit data with. Default 'a2*x*x+a1*x+a0'
-    # * *:initials* - initial values for coefficients used in fitting.
-    #   Default: {a2: 1, a1: 1, a0: 1}
-    # * *:term_options* - terminal options that should be setted to terminal before fit.
-    #   You can see them in Plot's documentation (or even better in gnuplot doc).
+    # @param :function [String] function to fit data with
+    # @param :initials [Hash] initial values for coefficients used in fitting
+    # @param :term_options [Hash] terminal options that should be setted to terminal before fit.
+    #   You can see them in Plot's documentation (or even better in gnuplot doc)
     #   Most useful here are ranges (xrange, yrange etc) and fit option which tunes fit parameters
-    #   (see {gnuplot doc}[http://www.gnuplot.info/docs_5.0/gnuplot.pdf] p. 122).
-    # * *options* - options passed to Gnuplot's fit such as *using*. They are covered in
-    #   {gnuplot doc}[http://www.gnuplot.info/docs_5.0/gnuplot.pdf](pp. 69-74)
-    # ====== Return value
-    # Fit returns hash of 4 elements:
-    # * *:formula_ds* - dataset with best fit curve as data
-    # * *:coefficients* - hash of calculated coefficients. So if you gave {via: [:a, :b, :c]} or
-    #   {initials: {a: 1, b: 1, c: 1} } it will return hash with keys :a, :b, :c and its values
-    # * *:deltas* - Gnuplot calculates possible deltas for coefficients during fitting and
-    #   *deltas* hash contains this deltas
-    # * *:data* - pointer to Datablock with given data
-    # ====== Examples
+    #   (see gnuplot doc - http://www.gnuplot.info/docs_5.0/gnuplot.pdf p. 122)
+    # @param options [Hash] options passed to Gnuplot's fit such as *using*. They are covered in
+    #   gnuplot doc - http://www.gnuplot.info/docs_5.0/gnuplot.pdf (pp. 69-74)
+    #
+    # @return [Hash] hash with four elements:
+    #   - :formula_ds - dataset with best fit curve as data
+    #   - :coefficients - hash of calculated coefficients. So if you gave
+    #     ``{ initials: {a: 1, b: 1, c: 1} }`` it will return hash with keys :a, :b, :c and its values
+    #   - :deltas - Gnuplot calculates possible deltas for coefficients during fitting and
+    #     deltas hash contains this deltas
+    #   - :data - pointer to Datablock with given data
+    # @example
     #   fit(some_data, function: 'exp(a/x)', initials: {a: 10}, term_option: { xrange: 1..100 })
     #   fit(some_dataset, using: '1:2:3')
     def fit(data, function: 'a2*x*x+a1*x+a0', initials: { a2: 1, a1: 1, a0: 1 }, term_options: {}, **options)
@@ -43,17 +47,24 @@ def fit(data, function: 'a2*x*x+a1*x+a0', initials: { a2: 1, a1: 1, a0: 1 }, ter
     end
 
     ##
-    # ====== Overview
     # Shortcut for fit with polynomial. Degree here is max power of *x* in polynomial.
-    # ====== Arguments
-    # * *data* - method accepts the same sources as Dataset.new and Dataset object
-    # * *:degree* - degree of polynomial
-    # * *options* - all of this options will be passed to *#fit* so you
-    #   can set here any *term_options*. If you pass here *:initials* hash, it
-    #   will be merged into default initals hash (all values are 1).
-    # ====== Return value
-    # See the same section for #fit.
-    # ====== Examples
+    #
+    # @param data [#to_gnuplot_points] method accepts the same sources as Dataset.new
+    #   and Dataset object
+    # @param :degree [Integer] degree of polynomial
+    # @param options [Hash] all of this options will be passed to #fit so you
+    #   can set here any options listed in its docs. If you pass here :initials hash, it
+    #   will be merged into default initals hash. Formula by default is
+    #   "xn*x**n + ... + x0*x**0", initials by default "{ an: 1, ..., a0: 1 }"
+    #
+    # @return [Hash] hash with four elements:
+    #   - :formula_ds - dataset with best fit curve as data
+    #   - :coefficients - hash of calculated coefficients. So for degree = 3
+    #     it will return hash with keys :a3, :a2, :a1, :a0 and calculated values
+    #   - :deltas - Gnuplot calculates possible deltas for coefficients during fitting and
+    #     deltas hash contains this deltas
+    #   - :data - pointer to Datablock with given data
+    # @example
     #   fit_poly(some_data, degree: 5, initials: { a4: 10, a2: -1 }, term_option: { xrange: 1..100 })
     #   #=> The same as:
     #   #=> fit(
@@ -72,22 +83,29 @@ def fit_poly(data, degree: 2, **options)
     end
 
     ##
-    # :method: fit_<function>
-    # :call-seq:
-    # fit_exp(data, **options) -> Hash
-    # fit_log(data, **options) -> Hash
-    # fit_sin(data, **options) -> Hash
+    # @!method fit_exp(data, **options)
+    # @!method fit_log(data, **options)
+    # @!method fit_sin(data, **options)
     #
-    # ====== Overview
     # Shortcuts for fitting with several math functions (exp, log, sin).
-    # ====== Arguments
-    # * *data* - method accepts the same sources as Dataset.new and Dataset object
-    # * *options* - all of this options will be passed to *#fit* so you
-    #   can set here any *term_options*. If you pass here *:initials* hash, it
-    #   will be merged into default initals hash { yoffset: 0.1, xoffset: 0.1, yscale: 1, xscale: 1 }
-    # ====== Return value
-    # See the same section for #fit.
-    # ====== Examples
+    #
+    # @param data [#to_gnuplot_points] method accepts the same sources as Dataset.new
+    #   and Dataset object
+    # @param options [Hash] all of this options will be passed to #fit so you
+    #   can set here any options listed in its docs. If you pass here :initials hash, it
+    #   will be merged into default initals hash. Formula by default is
+    #   "yscale * (yoffset + #{function name}((x - xoffset) / xscale))", initials by default
+    #   "{ yoffset: 0.1, xoffset: 0.1, yscale: 1, xscale: 1 }"
+    #
+    # @return [Hash] hash with four elements:
+    #   - :formula_ds - dataset with best fit curve as data
+    #   - :coefficients - hash of calculated coefficients. So for this case
+    #     it will return hash with keys :yoffset, :xoffset, :yscale, :xscale and calculated values
+    #   - :deltas - Gnuplot calculates possible deltas for coefficients during fitting and
+    #     deltas hash contains this deltas
+    #   - :data - pointer to Datablock with given data
+    #
+    # @example
     #   fit_exp(some_data, initials: { yoffset: -11 }, term_option: { xrange: 1..100 })
     #   #=> The same as:
     #   #=> fit(
@@ -116,6 +134,9 @@ def fit_poly(data, degree: 2, **options)
     ##
     # It takes some time to produce output so here we need
     # to wait for it.
+    #
+    # Max time to wait is stored in Settings.max_fit_delay, so one
+    # can change it in order to wait longer.
     def wait_for_output(term, variables)
       # now we should catch 'error' from terminal: it will contain approximation data
       # but we can get a real error instead of output, so lets wait for limited time