From 1595421ce0ab3cc943a22e7fef6a2294540fff20 Mon Sep 17 00:00:00 2001
From: mrkn <mrkn@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Wed, 12 Sep 2018 08:36:48 +0000
Subject: [PATCH] [DOC] Add the documentation of ArithmeticSequence

[ci-skip]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@64696 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 enumerator.c | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/enumerator.c b/enumerator.c
index ad76564484..94174dd3b9 100644
--- a/enumerator.c
+++ b/enumerator.c
@@ -2404,6 +2404,15 @@ stop_result(VALUE self)
     return rb_attr_get(self, id_result);
 }
 
+/*
+ * Document-class: Enumerator::ArithmeticSequence
+ *
+ * Enumerator::ArithmeticSequence is a subclass of Enumerator,
+ * that is a representation of sequences of numbers with common difference.
+ * The instances of this class can be generated by Range#step and Numeric#step
+ * methods.
+ */
+
 VALUE
 rb_arith_seq_new(VALUE obj, VALUE meth, int argc, VALUE const *argv,
                  rb_enumerator_size_func *size_fn,
@@ -2418,24 +2427,46 @@ rb_arith_seq_new(VALUE obj, VALUE meth, int argc, VALUE const *argv,
     return aseq;
 }
 
+/*
+ * call-seq: aseq.begin -> num
+ *
+ * Returns the number that defines the first element of this arithmetic
+ * sequence.
+ */
 static inline VALUE
 arith_seq_begin(VALUE self)
 {
     return rb_ivar_get(self, id_begin);
 }
 
+/*
+ * call-seq: aseq.end -> num or nil
+ *
+ * Returns the number that defines the end of this arithmetic sequence.
+ */
 static inline VALUE
 arith_seq_end(VALUE self)
 {
     return rb_ivar_get(self, id_end);
 }
 
+/*
+ * call-seq: aseq.step -> num
+ *
+ * Returns the number that defines the common difference between
+ * two adjacent elements in this arithmetic sequence.
+ */
 static inline VALUE
 arith_seq_step(VALUE self)
 {
     return rb_ivar_get(self, id_step);
 }
 
+/*
+ * call-seq: aseq.exclude_end? -> true or false
+ *
+ * Returns <code>true</code> if this arithmetic sequence excludes its end value.
+ */
 static inline VALUE
 arith_seq_exclude_end(VALUE self)
 {
@@ -2448,6 +2479,14 @@ arith_seq_exclude_end_p(VALUE self)
     return RTEST(arith_seq_exclude_end(self));
 }
 
+/*
+ * call-seq:
+ *   aseq.first -> num or nil
+ *   aseq.first(n) -> an_array
+ *
+ * Returns the first number in this arithmetic sequence,
+ * or an array of the first +n+ elements.
+ */
 static VALUE
 arith_seq_first(int argc, VALUE *argv, VALUE self)
 {
@@ -2476,6 +2515,14 @@ arith_seq_first(int argc, VALUE *argv, VALUE self)
     return rb_call_super(argc, argv);
 }
 
+/*
+ * call-seq:
+ *   aseq.last    -> num or nil
+ *   aseq.last(n) -> an_array
+ *
+ * Returns the last number in this arithmetic sequence,
+ * or an array of the last +n+ elements.
+ */
 static VALUE
 arith_seq_last(int argc, VALUE *argv, VALUE self)
 {
@@ -2539,6 +2586,12 @@ arith_seq_last(int argc, VALUE *argv, VALUE self)
     return ary;
 }
 
+/*
+ * call-seq:
+ *   aseq.inspect -> string
+ *
+ * Convert this arithmetic sequence to a printable form.
+ */
 static VALUE
 arith_seq_inspect(VALUE self)
 {
@@ -2597,6 +2650,13 @@ arith_seq_inspect(VALUE self)
     return str;
 }
 
+/*
+ * call-seq:
+ *   aseq == obj  -> true or false
+ *
+ * Returns <code>true</code> only if +obj+ is an Enumerator::ArithmeticSequence,
+ * has equivalent begin, end, step, and exclude_end? settings.
+ */
 static VALUE
 arith_seq_eq(VALUE self, VALUE other)
 {
@@ -2623,6 +2683,16 @@ arith_seq_eq(VALUE self, VALUE other)
     return Qtrue;
 }
 
+/*
+ * call-seq:
+ *   aseq.hash  -> integer
+ *
+ * Compute a hash-value for this arithmetic sequence.
+ * Two arithmetic sequences with same begin, end, step, and exclude_end?
+ * values will generate the same hash-value.
+ *
+ * See also Object#hash.
+ */
 static VALUE
 arith_seq_hash(VALUE self)
 {
@@ -2648,6 +2718,11 @@ struct arith_seq_gen {
     int excl;
 };
 
+/*
+ * call-seq:
+ *   aseq.each {|i| block } -> aseq
+ *   aseq.each              -> an_enumerator
+ */
 static VALUE
 arith_seq_each(VALUE self)
 {
@@ -2732,6 +2807,13 @@ arith_seq_float_step_size(double beg, double end, double step, int excl)
     return n + 1;
 }
 
+/*
+ * call-seq:
+ *   aseq.size -> num or nil
+ *
+ * Returns the number of elements in this arithmetic sequence if it is a finite
+ * sequence.  Otherwise, returns <code>nil</code>.
+ */
 static VALUE
 arith_seq_size(VALUE self)
 {