carray 1.4.0 → 1.5.5

data/{ca_iter_window.c → ext/ca_iter_window.c}

@@ -3,17 +3,15 @@
   ca_iter_window.c
 
   This file is part of Ruby/CArray extension library.
-  You can redistribute it and/or modify it under the terms of
-  the Ruby Licence.
 
-  Copyright (C) 2005 Hiroki Motoyoshi
+  Copyright (C) 2005-2020 Hiroki Motoyoshi
 
 ---------------------------------------------------------------------------- */
 
 #include "carray.h"
 
 typedef struct {
-  int8_t  rank;
+  int8_t  ndim;
   ca_size_t dim[CA_RANK_MAX];
   CArray *reference;
   CArray * (*kernel_at_addr)(void *, ca_size_t, CArray *);
@@ -27,7 +25,7 @@ typedef struct {
 
 VALUE rb_cCAWindowIterator;
 
-/* rdoc:
+/* yard:
   class CAWindowIterator < CAIterator # :nodoc:
   end
 */
@@ -59,7 +57,7 @@ ca_vi_kernel_at_index (void *it, ca_size_t *idx, CArray *ref)
 
   ca_update_mask(kernel);
 
-  for (i=0; i<kernel->rank; i++) {
+  for (i=0; i<kernel->ndim; i++) {
     j = idx[i];
     CA_CHECK_INDEX(j, vit->dim[i]);
     kernel->start[i] = j - vit->offset[i];
@@ -78,7 +76,7 @@ ca_vi_kernel_at_addr (void *it, ca_size_t addr, CArray *ref)
   ca_size_t *dim = vit->dim;
   ca_size_t idx[CA_RANK_MAX];
   int8_t i;
-  for (i=vit->rank-1; i>=0; i--) {
+  for (i=vit->ndim-1; i>=0; i--) {
     idx[i] = addr % dim[i];
     addr  /= dim[i];
   }
@@ -97,7 +95,7 @@ ca_vi_kernel_move_to_index (void *it, ca_size_t *idx, CArray *kern)
 
   ca_update_mask(kernel);
 
-  for (i=0; i<kernel->rank; i++) {
+  for (i=0; i<kernel->ndim; i++) {
     j = idx[i];
     CA_CHECK_INDEX(j, dim[i]);
     kernel->start[i] = j - offset[i];
@@ -116,7 +114,7 @@ ca_vi_kernel_move_to_addr (void *it, ca_size_t addr, CArray *ref)
   ca_size_t *dim = vit->dim;
   ca_size_t idx[CA_RANK_MAX];
   int8_t i;
-  for (i=vit->rank-1; i>=0; i--) {
+  for (i=vit->ndim-1; i>=0; i--) {
     idx[i] = addr % dim[i];
     addr  /= dim[i];
   }
@@ -136,12 +134,12 @@ ca_vi_setup (VALUE self, VALUE rref, VALUE rker)
   Data_Get_Struct(rref, CArray, ref);
   Data_Get_Struct(rker, CArray, ker);
 
-  if ( ref->rank != ker->rank ) {
-    rb_raise(rb_eRuntimeError, "rank mismatch between reference and kernel");
+  if ( ref->ndim != ker->ndim ) {
+    rb_raise(rb_eRuntimeError, "ndim mismatch between reference and kernel");
   }
 
-  it->rank      = ref->rank;
-  memcpy(it->dim, ref->dim, it->rank * sizeof(ca_size_t));
+  it->ndim      = ref->ndim;
+  memcpy(it->dim, ref->dim, it->ndim * sizeof(ca_size_t));
   it->reference = ref;
   it->kernel    = ker;
   it->kernel_at_addr  = ca_vi_kernel_at_addr;
@@ -149,7 +147,7 @@ ca_vi_setup (VALUE self, VALUE rref, VALUE rker)
   it->kernel_move_to_addr  = ca_vi_kernel_move_to_addr;
   it->kernel_move_to_index = ca_vi_kernel_move_to_index;
 
-  for (i=0; i<it->rank; i++) {
+  for (i=0; i<it->ndim; i++) {
     it->offset[i] = -(((CAWindow*)ker)->start[i]);
   }
 

data/{ca_obj_array.c → ext/ca_obj_array.c}

@@ -3,10 +3,8 @@
   ca_obj_array.c
 
   This file is part of Ruby/CArray extension library.
-  You can redistribute it and/or modify it under the terms of
-  the Ruby Licence.
 
-  Copyright (C) 2005 Hiroki Motoyoshi
+  Copyright (C) 2005-2020 Hiroki Motoyoshi
 
 ---------------------------------------------------------------------------- */
 
@@ -19,7 +17,7 @@
 
 VALUE rb_cCArray, rb_cCAWrap, rb_cCScalar, rb_cCAVirtual;
 
-/* rdoc:
+/* yard:
   class CArray
   end
   class CAWrap < CArray   # :nodoc:
@@ -42,7 +40,7 @@ double ca_mem_count = 0.0;
 
 /* Threshold for forced garbage collection and its default value */
 double ca_gc_interval; 
-const double ca_default_gc_interval = 40.0; /* 40MB */
+const double ca_default_gc_interval = 100.0; /* 100MB */
 
 #define MB (1024*1024)
 
@@ -60,27 +58,22 @@ ca_check_mem_count()
   }
 }
 
-/* rdoc:
-  # returns the threshold of incremented memory (MB) used by carray object 
-  # until start GC.
-  def CArray.gc_interval ()
-  end
-  # set the threshold of incremented memory (MB) used by carray object
-  # until start GC.
-  def CArray.gc_interval= (val)
-  end
-  # reset the counter for the GC start when the incremented memory 
-  # get larger than `CArray.gc_interval`.
-  def CArray.reset_gc_interval ()
-  end
-*/
+/* @private gc_interval
 
+Returns the threshold of incremented memory (MB) used by carray object 
+until start GC.
+*/
 static VALUE
 rb_ca_get_gc_interval (VALUE self)
 {
   return rb_float_new(ca_gc_interval);
 }
 
+/* @private gc_interval= (val)
+
+Sets the threshold of incremented memory (MB) used by carray object
+until start GC.
+*/
 static VALUE
 rb_ca_set_gc_interval (VALUE self, VALUE rth)
 {
@@ -92,6 +85,11 @@ rb_ca_set_gc_interval (VALUE self, VALUE rth)
   return rb_float_new(ca_gc_interval);
 }
 
+/* @private reset_gc_inverval
+
+Reset the counter for the GC start when the incremented memory 
+get larger than `CArray.gc_interval`.
+*/
 static VALUE
 rb_ca_reset_gc_interval (VALUE self)
 {
@@ -117,7 +115,7 @@ rb_ca_reset_gc_interval (VALUE self)
 
 static int
 carray_setup_i (CArray *ca,
-                int8_t data_type, int8_t rank, ca_size_t *dim, ca_size_t bytes,
+                int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
                 CArray *mask, int allocate, int use_calloc)
 {
   ca_size_t elements;
@@ -127,14 +125,14 @@ carray_setup_i (CArray *ca,
 
   /* check arguments */
   CA_CHECK_DATA_TYPE(data_type);
-  CA_CHECK_RANK(rank);
-  CA_CHECK_DIM(rank, dim);
+  CA_CHECK_RANK(ndim);
+  CA_CHECK_DIM(ndim, dim);
   CA_CHECK_BYTES(data_type, bytes);
 
   /* calculate total number of elements */
   elements = 1;
   length = bytes;
-  for (i=0; i<rank; i++) {
+  for (i=0; i<ndim; i++) {
     elements *= dim[i];
     length *= dim[i];
   }
@@ -153,11 +151,11 @@ carray_setup_i (CArray *ca,
 
   ca->data_type = data_type;
   ca->flags     = 0;
-  ca->rank      = rank;
+  ca->ndim      = ndim;
   ca->bytes     = bytes;
   ca->elements  = elements;
-  ca->dim       = ALLOC_N(ca_size_t, rank);
-  memcpy(ca->dim, dim, rank*sizeof(ca_size_t));
+  ca->dim       = ALLOC_N(ca_size_t, ndim);
+  memcpy(ca->dim, dim, ndim*sizeof(ca_size_t));
 
   if ( allocate ) {                                      /* allocate == true */
 
@@ -201,26 +199,26 @@ carray_setup_i (CArray *ca,
 
 int
 carray_setup (CArray *ca,
-  int8_t data_type, int8_t rank, ca_size_t *dim, ca_size_t bytes, CArray *mask)
+  int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes, CArray *mask)
 {
-  return carray_setup_i(ca, data_type, rank, dim, bytes, mask, 1, 0);
+  return carray_setup_i(ca, data_type, ndim, dim, bytes, mask, 1, 0);
 }
 
 int
 carray_safe_setup (CArray *ca,
-  int8_t data_type, int8_t rank, ca_size_t *dim, ca_size_t bytes, CArray *mask)
+  int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes, CArray *mask)
 {
-  return carray_setup_i(ca, data_type, rank, dim, bytes, mask, 1, 1);
+  return carray_setup_i(ca, data_type, ndim, dim, bytes, mask, 1, 1);
 }
 
 int
 ca_wrap_setup (CArray *ca,
-               int8_t data_type, int8_t rank, ca_size_t *dim, ca_size_t bytes,
+               int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
                CArray *mask, char *ptr)
 {
   int ret;
 
-  ret = carray_setup_i(ca, data_type, rank, dim, bytes, mask, 0, 0);
+  ret = carray_setup_i(ca, data_type, ndim, dim, bytes, mask, 0, 0);
   if ( (!ptr) && (ca->elements != 0) ) {
     rb_raise(rb_eRuntimeError, "wrapping NULL pointer with an non-empty array");
   }
@@ -230,49 +228,49 @@ ca_wrap_setup (CArray *ca,
 
 int
 ca_wrap_setup_null (CArray *ca,
-                    int8_t data_type, int8_t rank, ca_size_t *dim, ca_size_t bytes,
+                    int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
                     CArray *mask)
 {
   int ret;
 
-  ret = carray_setup_i(ca, data_type, rank, dim, bytes, mask, 0, 0);
+  ret = carray_setup_i(ca, data_type, ndim, dim, bytes, mask, 0, 0);
   ca->ptr = NULL;
   return ret;
 }
 
 CArray *
-carray_new (int8_t data_type, int8_t rank, ca_size_t *dim, ca_size_t bytes,
+carray_new (int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
             CArray *mask)
 {
   CArray *ca  = ALLOC(CArray);
-  carray_setup(ca, data_type, rank, dim, bytes, mask);
+  carray_setup(ca, data_type, ndim, dim, bytes, mask);
   return ca;
 }
 
 CArray *
-carray_new_safe (int8_t data_type, int8_t rank, ca_size_t *dim, ca_size_t bytes,
+carray_new_safe (int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
             CArray *mask)
 {
   CArray *ca  = ALLOC(CArray);
-  carray_safe_setup(ca, data_type, rank, dim, bytes, mask);
+  carray_safe_setup(ca, data_type, ndim, dim, bytes, mask);
   return ca;
 }
 
 CAWrap *
-ca_wrap_new (int8_t data_type, int8_t rank, ca_size_t *dim, ca_size_t bytes,
+ca_wrap_new (int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
             CArray *mask, char *ptr)
 {
   CAWrap *ca  = ALLOC(CAWrap);
-  ca_wrap_setup(ca, data_type, rank, dim, bytes, mask, ptr);
+  ca_wrap_setup(ca, data_type, ndim, dim, bytes, mask, ptr);
   return ca;
 }
 
 CAWrap *
-ca_wrap_new_null (int8_t data_type, int8_t rank, ca_size_t *dim, ca_size_t bytes,
+ca_wrap_new_null (int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
                   CArray *mask)
 {
   CAWrap *ca  = ALLOC(CAWrap);
-  ca_wrap_setup_null(ca, data_type, rank, dim, bytes, mask);
+  ca_wrap_setup_null(ca, data_type, ndim, dim, bytes, mask);
   return ca;
 }
 
@@ -313,7 +311,7 @@ cscalar_setup (CScalar *ca,
   ca->obj_type  = CA_OBJ_SCALAR;
   ca->data_type = data_type;
   ca->flags     = 0;
-  ca->rank      = 1;
+  ca->ndim      = 1;
   ca->bytes     = bytes;
   ca->elements  = 1;
   ca->dim       = &(ca->_dim);
@@ -388,7 +386,7 @@ ca_array_func_clone (void *ap)
 {
   CArray *ca = (CArray *) ap;
   CArray *co;
-  co = carray_new(ca->data_type, ca->rank, ca->dim, ca->bytes, ca->mask);
+  co = carray_new(ca->data_type, ca->ndim, ca->dim, ca->bytes, ca->mask);
   memcpy(co->ptr, ca->ptr, ca_length(ca));
   return co;
 }
@@ -407,9 +405,9 @@ ca_array_func_ptr_at_index (void *ap, ca_size_t *idx)
   ca_size_t *dim = ca->dim;
   int8_t     i;
   ca_size_t  n;
-  n = idx[0];                  /* n = idx[0]*dim[1]*dim[2]*...*dim[rank-1] */
-  for (i=1; i<ca->rank; i++) { /*    + idx[1]*dim[1]*dim[2]*...*dim[rank-1] */
-    n = dim[i]*n+idx[i];       /*    ... + idx[rank-2]*dim[1] + idx[rank-1] */
+  n = idx[0];                  /* n = idx[0]*dim[1]*dim[2]*...*dim[ndim-1] */
+  for (i=1; i<ca->ndim; i++) { /*    + idx[1]*dim[1]*dim[2]*...*dim[ndim-1] */
+    n = dim[i]*n+idx[i];       /*    ... + idx[ndim-2]*dim[1] + idx[ndim-1] */
   }
   return ca->ptr + ca->bytes * n;
 }
@@ -429,7 +427,7 @@ ca_array_func_fetch_index (void *ap, ca_size_t *idx, void *ptr)
   int8_t     i;
   ca_size_t  n;
   n = idx[0];
-  for (i=1; i<ca->rank; i++) {
+  for (i=1; i<ca->ndim; i++) {
     n = dim[i]*n+idx[i];
   }
   memcpy(ptr, ca->ptr + ca->bytes * n, ca->bytes);
@@ -450,7 +448,7 @@ ca_array_func_store_index (void *ap, ca_size_t *idx, void *ptr)
   int8_t     i;
   ca_size_t  n;
   n = idx[0];
-  for (i=1; i<ca->rank; i++) {
+  for (i=1; i<ca->ndim; i++) {
     n = dim[i]*n+idx[i];
   }
   memcpy(ca->ptr + ca->bytes * n, ptr, ca->bytes);
@@ -547,7 +545,7 @@ void
 ca_array_func_create_mask (void *ap)
 {
   CArray *ca = (CArray *) ap;
-  ca->mask = carray_new_safe(CA_BOOLEAN, ca->rank, ca->dim, 0, NULL);
+  ca->mask = carray_new_safe(CA_BOOLEAN, ca->ndim, ca->dim, 0, NULL);
 }
 
 ca_operation_function_t ca_array_func = {
@@ -654,18 +652,27 @@ ca_operation_function_t ca_scalar_func = {
 /* ------------------------------------------------------------------- */
 
 VALUE
-rb_carray_new (int8_t data_type, int8_t rank, ca_size_t *dim, ca_size_t bytes,
+rb_carray_new (int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
                CArray *mask)
 {
-  CArray *ca = carray_new(data_type, rank, dim, bytes, mask);
+  CArray *ca = carray_new(data_type, ndim, dim, bytes, mask);
   return ca_wrap_struct(ca);
 }
 
 VALUE
-rb_carray_new_safe (int8_t data_type, int8_t rank, ca_size_t *dim, ca_size_t bytes,
+rb_carray_new_safe (int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
                     CArray *mask)
 {
-  CArray *ca = carray_new_safe(data_type, rank, dim, bytes, mask);
+  CArray *ca = carray_new_safe(data_type, ndim, dim, bytes, mask);
+  return ca_wrap_struct(ca);
+}
+
+
+VALUE
+rb_ca_wrap_new (int8_t data_type, int8_t ndim, ca_size_t *dim, ca_size_t bytes,
+               CArray *mask, char *ptr)
+{
+  CAWrap *ca = ca_wrap_new(data_type, ndim, dim, bytes, mask, ptr);
   return ca_wrap_struct(ca);
 }
 
@@ -699,20 +706,16 @@ rb_ca_s_allocate (VALUE klass)
   return Data_Make_Struct(klass, CArray, ca_mark, ca_free, ca);
 }
 
-/* rdoc:
-  #  call-seq:
-  #     CArray.new(data_type, dim, bytes=0) { ... }
-  #
-  #  Constructs a new CArray object of <i>data_type</i>, which has the
-  #  rank and the dimensions specified by an <code>Array</code> of
-  #  <code>Integer</code> or an argument list of <code>Integer</code>.
-  #  The byte size of each element for the fixed length data type
-  #  (<code>data_type == CA_FIXLEN</code>) is specified optional argument
-  #  <i>bytes</i>. Otherwise, this optional argument has no
-  #  effect. If the block is given, the new CArray
-  #  object will be initialized by the value returned from the block.
-  def CArray.new(data_type, dim, bytes=0)
-  end
+/* @overload  initialize(data_type, dim, bytes=0) { ... }
+
+Constructs a new CArray object of <i>data_type</i>, which has the
+ndim and the dimensions specified by an <code>Array</code> of
+<code>Integer</code> or an argument list of <code>Integer</code>.
+The byte size of each element for the fixed length data type
+(<code>data_type == CA_FIXLEN</code>) is specified optional argument
+<i>bytes</i>. Otherwise, this optional argument has no
+effect. If the block is given, the new CArray
+object will be initialized by the value returned from the block.
 */
 
 static VALUE
@@ -720,7 +723,7 @@ rb_ca_initialize (int argc, VALUE *argv, VALUE self)
 {
   volatile VALUE rtype, rdim, ropt, rbytes = Qnil;
   CArray *ca;
-  int8_t data_type, rank;
+  int8_t data_type, ndim;
   ca_size_t dim[CA_RANK_MAX];
   ca_size_t bytes;
   int8_t i;
@@ -732,13 +735,13 @@ rb_ca_initialize (int argc, VALUE *argv, VALUE self)
   rb_ca_data_type_import(self, rtype);
 
   Check_Type(rdim, T_ARRAY);
-  rank = RARRAY_LEN(rdim);
-  for (i=0; i<rank; i++) {
+  ndim = RARRAY_LEN(rdim);
+  for (i=0; i<ndim; i++) {
     dim[i] = NUM2SIZE(rb_ary_entry(rdim, i));
   }
 
   Data_Get_Struct(self, CArray, ca);
-  carray_safe_setup(ca, data_type, rank, dim, bytes, NULL);
+  carray_safe_setup(ca, data_type, ndim, dim, bytes, NULL);
 
   if ( rb_block_given_p() ) {
     volatile VALUE rval = rb_yield(self);
@@ -750,6 +753,12 @@ rb_ca_initialize (int argc, VALUE *argv, VALUE self)
   return Qnil;
 }
 
+/* @overload  fixlen(*dim, bytes: ) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:fixlen, dim, bytes: ) { ... }`
+*/
+
 static VALUE
 rb_ca_s_fixlen (int argc, VALUE *argv, VALUE klass)  
 {                                                     
@@ -759,56 +768,184 @@ rb_ca_s_fixlen (int argc, VALUE *argv, VALUE klass)
   return rb_class_new_instance(3, args, klass);       
 }
 
-#define rb_ca_s_type(type, code)                      \
-rb_ca_s_## type (int argc, VALUE *argv, VALUE klass)  \
-{                                                     \
-  volatile VALUE ropt = rb_pop_options(&argc, &argv); \
-  volatile VALUE rdim = rb_ary_new4(argc, argv);      \
-  VALUE args[3] = { INT2NUM(code), rdim, ropt };      \
-  return rb_class_new_instance(3, args, klass);       \
+#define rb_ca_s_body(code)                              \
+{                                                       \
+  if ( argc == 0 ) {                                    \
+    return ca_data_type_class(code);                    \
+  }                                                     \
+  else {                                                \
+    volatile VALUE ropt = rb_pop_options(&argc, &argv); \
+    volatile VALUE rdim = rb_ary_new4(argc, argv);      \
+    VALUE args[3] = { INT2NUM(code), rdim, ropt };      \
+    return rb_class_new_instance(3, args, klass);       \
+  }                                                     \
 }
 
-/*
- *  call-seq:
- *     CArray.int8(dim0, dim1, ...) { ... }     -> CArray
- *     CArray.uint8(dim0, dim1, ...) { ... }    -> CArray
- *     CArray.int16(dim0, dim1, ...) { ... }    -> CArray
- *     CArray.uint16(dim0, dim1, ...) { ... }   -> CArray
- *     CArray.int32(dim0, dim1, ...) { ... }    -> CArray
- *     CArray.uint32(dim0, dim1, ...) { ... }   -> CArray
- *     CArray.int64(dim0, dim1, ...) { ... }    -> CArray
- *     CArray.uint64(dim0, dim1, ...) { ... }   -> CArray
- *     CArray.float32(dim0, dim1, ...) { ... }  -> CArray
- *     CArray.float64(dim0, dim1, ...) { ... }  -> CArray
- *     CArray.float128(dim0, dim1, ...) { ... } -> CArray
- *     CArray.cmplx64(dim0, dim1, ...) { ... }  -> CArray
- *     CArray.cmplx128(dim0, dim1, ...) { ... } -> CArray
- *     CArray.cmplx256(dim0, dim1, ...) { ... } -> CArray
- *     CArray.object(dim0, dim1, ...) { ... }   -> CArray
- *
- */
+/* @overload  boolean(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:boolean, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_boolean (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_BOOLEAN);
+}
+
+/* @overload  int8(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:int8, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_int8 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_INT8);
+}
+
+/* @overload  uint8(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:uint8, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_uint8 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_UINT8);
+}
+
+/* @overload  int16(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:int16, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_int16 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_INT16);
+}
+
+/* @overload  uint16(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:uint16, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_uint16 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_UINT16);
+}
+
+/* @overload  int32(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:int32, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_int32 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_INT32);
+}
+
+/* @overload  uint32(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:uint32, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_uint32 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_UINT32);
+}
+
+/* @overload  int64(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:int64, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_int64 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_INT64);
+}
+
+/* @overload  uint64(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:uint64, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_uint64 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_UINT64);
+}
+
+/* @overload  float32(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:float32, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_float32 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_FLOAT32);
+}
+
+/* @overload  float64(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:float64, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_float64 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_FLOAT64);
+}
+
+/* @overload  float128(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:float128, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_float128 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_FLOAT128);
+}
 
-static VALUE rb_ca_s_VALUE();
-
-static VALUE rb_ca_s_type(boolean,  CA_BOOLEAN);
-static VALUE rb_ca_s_type(int8,     CA_INT8);
-static VALUE rb_ca_s_type(uint8,    CA_UINT8);
-static VALUE rb_ca_s_type(int16,    CA_INT16);
-static VALUE rb_ca_s_type(uint16,   CA_UINT16);
-static VALUE rb_ca_s_type(int32,    CA_INT32);
-static VALUE rb_ca_s_type(uint32,   CA_UINT32);
-static VALUE rb_ca_s_type(int64,    CA_INT64);
-static VALUE rb_ca_s_type(uint64,   CA_UINT64);
-static VALUE rb_ca_s_type(float32,  CA_FLOAT32);
-static VALUE rb_ca_s_type(float64,  CA_FLOAT64);
-static VALUE rb_ca_s_type(float128, CA_FLOAT128);
 #ifdef HAVE_COMPLEX_H
-static VALUE rb_ca_s_type(cmplx64,  CA_CMPLX64);
-static VALUE rb_ca_s_type(cmplx128, CA_CMPLX128);
-static VALUE rb_ca_s_type(cmplx256, CA_CMPLX256);
+/* @overload  cmplx64(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:cmplx64, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_cmplx64 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_CMPLX64);
+}
+
+/* @overload  cmplx128(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:cmplx128, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_cmplx128 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_CMPLX128);
+}
+
+/* @overload  cmplx256(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:cmplx256, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_cmplx256 (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_CMPLX256);
+}
 #endif
-static VALUE rb_ca_s_type(VALUE,    CA_OBJECT);
 
+/* @overload  object(*dim) { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:object, dim, bytes: bytes) { ... }`
+*/
+static VALUE rb_ca_s_VALUE (int argc, VALUE *argv, VALUE klass)
+{
+  rb_ca_s_body(CA_OBJECT);
+}
+
+/* @overload  initialize_copy(other)
+
+*/
 static VALUE
 rb_ca_initialize_copy (VALUE self, VALUE other)
 {
@@ -820,16 +957,17 @@ rb_ca_initialize_copy (VALUE self, VALUE other)
   Data_Get_Struct(other, CArray, cs);
 
   ca_update_mask(cs);
-  carray_setup(ca, cs->data_type, cs->rank, cs->dim, cs->bytes, cs->mask);
+  carray_setup(ca, cs->data_type, cs->ndim, cs->dim, cs->bytes, cs->mask);
 
   memcpy(ca->ptr, cs->ptr, ca_length(cs));
 
   return self;
 }
 
-/* rdoc:
-   def CArray.wrap (data_type, dim, bytes=0) # { wrapped_object }
-   end
+/* @overload wrap (data_type, dim, bytes=0) { target }
+
+[TBD] (Construction)
+target should have method "wrap_as_carray(obj)"
 */
 
 static VALUE
@@ -837,7 +975,7 @@ rb_ca_s_wrap (int argc, VALUE *argv, VALUE self)
 {
   volatile VALUE obj, target, rtype, rdim, ropt, rbytes = Qnil;
   CArray *ca;
-  int8_t data_type, rank;
+  int8_t data_type, ndim;
   ca_size_t dim[CA_RANK_MAX];
   ca_size_t bytes;
   int8_t i;
@@ -848,15 +986,15 @@ rb_ca_s_wrap (int argc, VALUE *argv, VALUE self)
   rb_ca_guess_type_and_bytes(rtype, rbytes, &data_type, &bytes);
 
   Check_Type(rdim, T_ARRAY);
-  rank = RARRAY_LEN(rdim);
-  for (i=0; i<rank; i++) {
+  ndim = RARRAY_LEN(rdim);
+  for (i=0; i<ndim; i++) {
     dim[i] = NUM2SIZE(rb_ary_entry(rdim, i));
   }
 
   target = rb_yield_values(0);
 
   obj = Data_Make_Struct(rb_cCAWrap, CAWrap, ca_mark, ca_free, ca);
-  ca_wrap_setup_null(ca, data_type, rank, dim, bytes, NULL);
+  ca_wrap_setup_null(ca, data_type, ndim, dim, bytes, NULL);
 
   rb_funcall(target, rb_intern("wrap_as_carray"), 1, obj);
   rb_ivar_set(obj, rb_intern("referred_object"), target);
@@ -865,13 +1003,13 @@ rb_ca_s_wrap (int argc, VALUE *argv, VALUE self)
 }
 
 VALUE
-rb_carray_wrap_ptr (int8_t data_type, int8_t rank, ca_size_t *dim,
+rb_carray_wrap_ptr (int8_t data_type, int8_t ndim, ca_size_t *dim,
         ca_size_t bytes, CArray *mask, char *ptr, VALUE refer)
 {
   volatile VALUE obj;
   CArray *ca;
 
-  ca  = ca_wrap_new(data_type, rank, dim, bytes, mask, ptr);
+  ca  = ca_wrap_new(data_type, ndim, dim, bytes, mask, ptr);
   obj = ca_wrap_struct(ca);
 
   rb_ivar_set(obj, rb_intern("referred_object"), refer);
@@ -888,16 +1026,16 @@ rb_cs_s_allocate (VALUE klass)
   return Data_Make_Struct(klass, CScalar, ca_mark, ca_free, ca);
 }
 
-/* rdoc:
-  #  call-seq:
-  #     CScalar.new(data_type, bytes=0) { ... }
-  #
-  #  Constructs a new CScalar object of <i>data_type</i>.
-  #  The byte size of each element for the fixed length data type
-  #  (<code>data_type == CA_FIXLEN</code>) is specified optional argument
-  #  <i>bytes</i>. Otherwise, this optional argument has no
-  #  effect. If the block is given, the new CScalar
-  #  object will be initialized by the value returned from the block.
+/* 
+ call-seq:
+     CScalar.new(data_type, bytes=0) { ... }
+
+  Constructs a new CScalar object of <i>data_type</i>.
+  The byte size of each element for the fixed length data type
+  (<code>data_type == CA_FIXLEN</code>) is specified optional argument
+  <i>bytes</i>. Otherwise, this optional argument has no
+  effect. If the block is given, the new CScalar
+  object will be initialized by the value returned from the block.
   def CScalar.new(data_type,bytes=0)
   end
 */
@@ -929,6 +1067,12 @@ rb_cs_initialize (int argc, VALUE *argv, VALUE self)
   return Qnil;
 }
 
+/* @overload  fixlen(*dim, bytes: ) { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:fixlen, bytes: ) { ... }`
+*/
+
 static VALUE
 rb_cs_s_fixlen (int argc, VALUE *argv, VALUE klass)  
 {                                                     
@@ -940,8 +1084,7 @@ rb_cs_s_fixlen (int argc, VALUE *argv, VALUE klass)
   return rb_class_new_instance(2, args, klass);       
 }
 
-#define rb_cs_s_type(type, code)                      \
-rb_cs_s_## type (int argc, VALUE *argv, VALUE klass)  \
+#define rb_cs_s_body(code)                      \
 {                                                     \
   volatile VALUE ropt = rb_pop_options(&argc, &argv); \
   VALUE args[2] = { INT2NUM(code), ropt };            \
@@ -951,47 +1094,172 @@ rb_cs_s_## type (int argc, VALUE *argv, VALUE klass)  \
   return rb_class_new_instance(2, args, klass);       \
 }
 
-static VALUE rb_cs_s_type(boolean,  CA_BOOLEAN);
-static VALUE rb_cs_s_type(int8,     CA_INT8);
-static VALUE rb_cs_s_type(uint8,    CA_UINT8);
-static VALUE rb_cs_s_type(int16,    CA_INT16);
-static VALUE rb_cs_s_type(uint16,   CA_UINT16);
-static VALUE rb_cs_s_type(int32,    CA_INT32);
-static VALUE rb_cs_s_type(uint32,   CA_UINT32);
-static VALUE rb_cs_s_type(int64,    CA_INT64);
-static VALUE rb_cs_s_type(uint64,   CA_UINT64);
-static VALUE rb_cs_s_type(float32,  CA_FLOAT32);
-static VALUE rb_cs_s_type(float64,  CA_FLOAT64);
-static VALUE rb_cs_s_type(float128, CA_FLOAT128);
+/* @overload  boolean() { ... } 
+
+(Construction)
+Short-Hand of `CArray.new(:boolean) { ... }`
+*/
+static VALUE 
+rb_cs_s_boolean (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_BOOLEAN);
+}
+
+/* @overload  int8() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:int8) { ... }`
+*/
+static VALUE 
+rb_cs_s_int8 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_INT8);
+}
+
+/* @overload uint8() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:uint8) { ... }`
+*/
+static VALUE 
+rb_cs_s_uint8 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_UINT8);
+}
+
+
+/* @overload int16() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:int16) { ... }`
+*/
+static VALUE 
+rb_cs_s_int16 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_INT16);
+}
+
+/* @overload uint16() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:uint16) { ... }`
+*/
+static VALUE 
+rb_cs_s_uint16 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_UINT16);
+}
+
+/* @overload int32() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:int32) { ... }`
+*/
+static VALUE 
+rb_cs_s_int32 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_INT32);
+}
+
+/* @overload uint32() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:uint32) { ... }`
+*/
+static VALUE 
+rb_cs_s_uint32 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_UINT32);
+}
+
+/* @overload int64() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:int64) { ... }`
+*/
+static VALUE 
+rb_cs_s_int64 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_INT64);
+}
+
+/* @overload uint64() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:uint64) { ... }`
+*/
+static VALUE 
+rb_cs_s_uint64 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_UINT64);
+}
+
+/* @overload float32() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:float32) { ... }`
+*/
+static VALUE 
+rb_cs_s_float32 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_FLOAT32);
+}
+
+/* @overload float64() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:float64) { ... }`
+*/
+static VALUE 
+rb_cs_s_float64 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_FLOAT64);
+}
+
+/* @overload float128() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:float128) { ... }`
+*/
+static VALUE 
+rb_cs_s_float128 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_FLOAT128);
+}
+
 #ifdef HAVE_COMPLEX_H
-static VALUE rb_cs_s_type(cmplx64,  CA_CMPLX64);
-static VALUE rb_cs_s_type(cmplx128, CA_CMPLX128);
-static VALUE rb_cs_s_type(cmplx256, CA_CMPLX256);
+/* @overload cmplx64() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:cmplx64) { ... }`
+*/
+static VALUE 
+rb_cs_s_cmplx64 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_CMPLX64);
+}
+
+/* @overload cmplx128() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:cmplx128) { ... }`
+*/
+static VALUE 
+rb_cs_s_cmplx128 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_CMPLX128);
+}
+
+/* @overload cmplx256() { ... } 
+
+(Construction)
+Short-Hand of `CScalar.new(:cmplx256) { ... }`
+*/
+static VALUE 
+rb_cs_s_cmplx256 (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_CMPLX256);
+}
 #endif
-static VALUE rb_cs_s_type(VALUE,    CA_OBJECT);
 
-/*
- *  call-seq:
- *     CScalar.int8() { ... }     -> CScalar
- *     CScalar.uint8() { ... }    -> CScalar
- *     CScalar.int16() { ... }    -> CScalar
- *     CScalar.uint16() { ... }   -> CScalar
- *     CScalar.int32() { ... }    -> CScalar
- *     CScalar.uint32() { ... }   -> CScalar
- *     CScalar.int64() { ... }    -> CScalar
- *     CScalar.uint64() { ... }   -> CScalar
- *     CScalar.float32() { ... }  -> CScalar
- *     CScalar.float64() { ... }  -> CScalar
- *     CScalar.float128() { ... } -> CScalar
- *     CScalar.cmplx64() { ... }  -> CScalar
- *     CScalar.cmplx128() { ... } -> CScalar
- *     CScalar.cmplx256() { ... } -> CScalar
- *     CScalar.object() { ... }   -> CScalar
- *
- */
+/* @overload object() { ... } 
 
-static VALUE
-rb_cs_s_VALUE();
+(Construction)
+Short-Hand of `CScalar.new(:object) { ... }`
+*/
+static VALUE 
+rb_cs_s_VALUE (int argc, VALUE *argv, VALUE klass) {
+  rb_cs_s_body(CA_OBJECT);
+}
+
+/* @overload  initialize_copy(other)
+
+*/
 
 static VALUE
 rb_cs_initialize_copy (VALUE self, VALUE other)
@@ -1026,6 +1294,10 @@ rb_cs_coerce (VALUE self, VALUE other)
 }
 */
 
+/* @private
+@overload mem_usage
+*/
+
 static VALUE
 rb_ca_mem_usage (VALUE self)
 {
@@ -1041,7 +1313,10 @@ Init_ca_obj_array ()
 
   /* ------------------------------------------------------------------- */
   ca_gc_interval = ca_default_gc_interval;
+
+  /* @private */
   rb_define_const(rb_cCArray, "DEFAULT_GC_INTERVAL", rb_float_new(ca_default_gc_interval));
+
   rb_define_singleton_method(rb_cCArray, "gc_interval", rb_ca_get_gc_interval, 0);
   rb_define_singleton_method(rb_cCArray, "gc_interval=", rb_ca_set_gc_interval, 1);
   rb_define_singleton_method(rb_cCArray, "reset_gc_interval", rb_ca_reset_gc_interval, 0);
@@ -1130,7 +1405,7 @@ Init_ca_obj_array ()
 }
 
 
-/* rdoc:
+/* yard:
   # call-seq:
   #    CArray.boolean(...) { init_value }
   #    CArray.int8(...) { init_value }