Better documentation for statistical methods

Rakefile

@@ -1,6 +1,7 @@
 require "bundler/gem_tasks"
 require "rdoc/task"
 require "sdoc"
+
 autoload :FileUtils, "fileutils"
 
 Dir["tasks/**/*.rake"].each do |rake|
@@ -11,11 +12,12 @@ RDoc::Task.new do |rdoc|
   rdoc.rdoc_dir = "doc/rdoc"
   rdoc.title = "Rupee Documentation"
 
-  rdoc.options << "-f" << "sdoc"
-  rdoc.options << "-T" << "rails"
+  rdoc.options << "-f" << "sdoc"         # format with SDoc
+  rdoc.options << "-T" << "rails"        # use the Rails template
   rdoc.options << "-c" << "utf-8"
-  rdoc.options << "-g"
-  rdoc.options << "-m" << "README.rdoc"
+  rdoc.options << "-g"                   # link to GitHub
+  rdoc.options << "-m" << "README.rdoc"  # use README.rdoc as main file
+  rdoc.options << "-v"                   # verbose output
 
   rdoc.rdoc_files.include "README.rdoc"
   rdoc.rdoc_files.include "ext/**/*.{c, h, rb}"
@@ -24,5 +26,6 @@ end
 
 desc "Copies the documentation files to the path specified in the $RUPEE_DOC environment variable"
 task :docs do
-  FileUtils.cp_r "doc/rdoc/.", "#{ENV['RUPEE_DOC']}"
+  FileUtils.cp_r "doc/rdoc/.", "#{ENV['RUPEE_DOC']}",
+    :remove_destination => true
 end

ext/rupee/statistics.c

@@ -125,10 +125,6 @@ std(values, len)
  *
  * Returns the standard normal cumulative distribution (has a mean of zero and
  * a standard deviation of one).
- *
- * ==== Arguments
- *
- * * +z+ - The value for which you want the distribution
  */
 static VALUE
 rupee_cnd(self, _z)
@@ -137,6 +133,10 @@ rupee_cnd(self, _z)
   return rb_float_new(cnd(NUM2DBL(_z)));
 }
 
+/* call-seq: correlation(xvalues, yvalues)
+ *
+ * Returns the correlation of the supplied x- and y-values.
+ */
 static VALUE
 rupee_corr(self, _xvals, _yvals)
   VALUE self, _xvals, _yvals;
@@ -150,6 +150,10 @@ rupee_corr(self, _xvals, _yvals)
   return rb_float_new(corr(xvals, yvals, len));
 }
 
+/* call-seq: covariance(xvalues, yvalues)
+ *
+ * Returns the covariance of the supplied x- and y-values.
+ */
 static VALUE
 rupee_cov(self, _xvals, _yvals)
   VALUE self, _xvals, _yvals;
@@ -163,6 +167,10 @@ rupee_cov(self, _xvals, _yvals)
   return rb_float_new(cov(xvals, yvals, len));
 }
 
+/* call-seq: mean(values)
+ *
+ * Finds the mean of the specified values.
+ */
 static VALUE
 rupee_mean(self, _values)
   VALUE self, _values;
@@ -175,6 +183,10 @@ rupee_mean(self, _values)
   return rb_float_new(mean(values, len));
 }
 
+/* call-seq: standard_deviation(values)
+ *
+ * Finds the standard deviation of the specified values.
+ */
 static VALUE
 rupee_std(self, _values)
   VALUE self, _values;
@@ -187,6 +199,10 @@ rupee_std(self, _values)
   return rb_float_new(std(values, len));
 }
 
+/* call-seq: sum(values)
+ *
+ * Finds the sum of the specified values.
+ */
 static VALUE
 rupee_sum(self, _values)
   VALUE self, _values;
@@ -199,6 +215,10 @@ rupee_sum(self, _values)
   return rb_float_new(sum(values, len));
 }
 
+/* call-seq: variance(values)
+ *
+ * Finds the variance of the specified values.
+ */
 static VALUE
 rupee_var(self, _values)
   VALUE self, _values;

lib/rupee/security.rb

@@ -40,8 +40,15 @@ class << self
       #   attr_accessor :price
       #   attr_alias :value, :price
       # 
-      # would add both a <tt>value</tt> and a <tt>value=</tt> that are equivalent
-      # to their <tt>price</tt> counterparts.
+      # would add both a <tt>value</tt> and a <tt>value=</tt> that are
+      # equivalent to their <tt>price</tt> counterparts and would modify the
+      # <tt>@price</tt> instance variable. On the other hand,
+      #
+      #   attr :price
+      #   attr_alias :value, :price
+      # 
+      # would only add  <tt>value</tt> method that's equivalent to
+      # <tt>price</tt>.
       def attr_alias(new_read, old_read)
         alias_method(new_read, old_read) if method_defined?(old_read)
         new_write = "#{new_read}="