4 files changed, 256 insertions, 9 deletions
diff --git a/include/mruby/array.h b/include/mruby/array.h
index 8f9d5d502..e553faf92 100644
--- a/include/mruby/array.h
+++ b/include/mruby/array.h
@@ -54,14 +54,60 @@ MRB_API mrb_value mrb_ary_new_capa(mrb_state*, mrb_int);
  *      Array.new
  *
  * @param mrb The mruby state reference.
- * @return The initialized array
+ * @return The initialized array.
  */
 MRB_API mrb_value mrb_ary_new(mrb_state *mrb);
 
+/*
+ * Initializes a new array with initial values
+ *
+ * Equivalent to:
+ *
+ *      Array[value1, value2, ...]
+ *
+ * @param mrb The mruby state reference.
+ * @param size The numer of values.
+ * @param vals The actual values.
+ * @return The initialized array.
+ */
 MRB_API mrb_value mrb_ary_new_from_values(mrb_state *mrb, mrb_int size, const mrb_value *vals);
+
+/*
+ * Initializes a new array with two initial values
+ *
+ * Equivalent to:
+ *
+ *      Array[car, cdr]
+ *
+ * @param mrb The mruby state reference.
+ * @param car The first value.
+ * @param cdr The second value.
+ * @return The initialized array.
+ */
 MRB_API mrb_value mrb_assoc_new(mrb_state *mrb, mrb_value car, mrb_value cdr);
-MRB_API void mrb_ary_concat(mrb_state*, mrb_value, mrb_value);
-MRB_API mrb_value mrb_ary_splat(mrb_state*, mrb_value);
+
+/*
+ * Concatenate two arrays. The target array will be modified
+ *
+ * Equivalent to:
+ *      ary.concat(other)
+ *
+ * @param mrb The mruby state reference.
+ * @param self The target array.
+ * @param other The array that will be concatenated to self.
+ */
+MRB_API void mrb_ary_concat(mrb_state *mrb, mrb_value self, mrb_value other);
+
+/*
+ * Create an array from the input. It tries calling to_a on the
+ * value. If value does not respond to that, it creates a new
+ * array with just this value.
+ *
+ * @param mrb The mruby state reference.
+ * @param value The value to change into an array.
+ * @return An array representation of value.
+ */
+MRB_API mrb_value mrb_ary_splat(mrb_state *mrb, mrb_value value);
 
 /*
  * Pushes value into array.
@@ -84,8 +130,8 @@ MRB_API void mrb_ary_push(mrb_state *mrb, mrb_value array, mrb_value value);
  *      ary.pop
  *
  * @param mrb The mruby state reference.
- * @param ary The array from which the value will be poped.
- * @return The poped value.
+ * @param ary The array from which the value will be popped.
+ * @return The popped value.
  */
 MRB_API mrb_value mrb_ary_pop(mrb_state *mrb, mrb_value ary);
 
@@ -117,14 +163,81 @@ MRB_API mrb_value mrb_ary_ref(mrb_state *mrb, mrb_value ary, mrb_int n);
  */
 MRB_API void mrb_ary_set(mrb_state *mrb, mrb_value ary, mrb_int n, mrb_value val);
 
-MRB_API void mrb_ary_replace(mrb_state *mrb, mrb_value a, mrb_value b);
+/*
+ * Replace the array with another array
+ *
+ * Equivalent to:
+ *
+ *      ary.replace(other)
+ *
+ * @param mrb The mruby state reference
+ * @param self The target array.
+ * @param other The array to replace it with.
+ */
+MRB_API void mrb_ary_replace(mrb_state *mrb, mrb_value self, mrb_value other);
 MRB_API mrb_value mrb_check_array_type(mrb_state *mrb, mrb_value self);
+
+/*
+ * Unshift an element into an array
+ *
+ * Equivalent to:
+ *
+ *     ary.unshift(item)
+ *
+ * @param mrb The mruby state reference.
+ * @param self The target array.
+ * @param item The item to unshift.
+ */
 MRB_API mrb_value mrb_ary_unshift(mrb_state *mrb, mrb_value self, mrb_value item);
 MRB_API mrb_value mrb_ary_entry(mrb_value ary, mrb_int offset);
+
+/*
+ * Shifts the first element from the array.
+ *
+ * Equivalent to:
+ *
+ *      ary.shift
+ *
+ * @param mrb The mruby state reference.
+ * @param self The array from which the value will be shifted.
+ * @return The shifted value.
+ */
 MRB_API mrb_value mrb_ary_shift(mrb_state *mrb, mrb_value self);
+
+/*
+ * Removes all elements from this array
+ *
+ * Equivalent to:
+ *
+ *      ary.clear
+ *
+ * @param mrb The mruby state reference.
+ * @param self The target array.
+ * @return self
+ */
 MRB_API mrb_value mrb_ary_clear(mrb_state *mrb, mrb_value self);
+
+/*
+ * Join the array elements together in a string
+ *
+ * Equivalent to:
+ *
+ *      ary.join(sep="")
+ *
+ * @param mrb The mruby state reference.
+ * @param ary The target array
+ * @param sep The separater, can be NULL
+ */
 MRB_API mrb_value mrb_ary_join(mrb_state *mrb, mrb_value ary, mrb_value sep);
-MRB_API mrb_value mrb_ary_resize(mrb_state *mrb, mrb_value ary, mrb_int len);
+
+/*
+ * Update the capacity of the array
+ *
+ * @param mrb The mruby state reference.
+ * @param ary The target array.
+ * @param new_len The new capacity of the array
+ */
+MRB_API mrb_value mrb_ary_resize(mrb_state *mrb, mrb_value ary, mrb_int new_len);
 
 static inline mrb_int
 mrb_ary_len(mrb_state *mrb, mrb_value ary)
diff --git a/include/mruby/hash.h b/include/mruby/hash.h
index 922353322..55ad6a921 100644
--- a/include/mruby/hash.h
+++ b/include/mruby/hash.h
@@ -28,40 +28,126 @@ MRB_API mrb_value mrb_hash_new_capa(mrb_state*, int);
 
 /*
  * Initializes a new hash.
+ *
+ * Equivalent to:
+ *
+ *      Hash.new
+ *
+ * @param mrb The mruby state reference.
+ * @return The initialized hash.
  */
 MRB_API mrb_value mrb_hash_new(mrb_state *mrb);
 
 /*
  * Sets a keys and values to hashes.
+ *
+ * Equivalent to:
+ *
+ *      hash[key] = val
+ *
+ * @param mrb The mruby state reference.
+ * @param hash The target hash.
+ * @param key The key to set.
+ * @param val The value to set.
+ * @return The value.
  */
 MRB_API void mrb_hash_set(mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value val);
 
 /*
- * Gets a value from a key.
+ * Gets a value from a key. If the key is not found, the default of the
+ * hash is used.
+ *
+ * Equivalent to:
+ *
+ *     hash[key]
+ *
+ * @param mrb The mruby state reference.
+ * @param hash The target hash.
+ * @param key The key to get.
+ * @return The found value.
  */
 MRB_API mrb_value mrb_hash_get(mrb_state *mrb, mrb_value hash, mrb_value key);
 
+/*
+ * Gets a value from a key. If the key is not found, the default parameter is
+ * used.
+ *
+ * Equivalent to:
+ *
+ *     hash.hash_key?(key) ? hash[key] : def
+ *
+ * @param mrb The mruby state reference.
+ * @param hash The target hash.
+ * @param key The key to get.
+ * @param def The default value.
+ * @return The found value.
+ */
 MRB_API mrb_value mrb_hash_fetch(mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value def);
 
 /*
  * Deletes hash key and value pair.
+ *
+ * Equivalent to:
+ *
+ *     hash.delete(key)
+ *
+ * @param mrb The mruby state reference.
+ * @param hash The target hash.
+ * @param key The key to delete.
+ * @return The deleted value.
  */
 MRB_API mrb_value mrb_hash_delete_key(mrb_state *mrb, mrb_value hash, mrb_value key);
 
 /*
  * Gets an array of keys.
+ *
+ * Equivalent to:
+ *
+ *     hash.keys
+ *
+ * @param mrb The mruby state reference.
+ * @param hash The target hash.
+ * @return An array with the keys of the hash.
  */
 MRB_API mrb_value mrb_hash_keys(mrb_state *mrb, mrb_value hash);
 MRB_API mrb_value mrb_check_hash_type(mrb_state *mrb, mrb_value hash);
+
+/*
+ * Check if the hash is empty
+ *
+ * Equivalent to:
+ *
+ *     hash.empty?
+ *
+ * @param mrb The mruby state reference.
+ * @param self The target hash.
+ * @return True if the hash is empty, false otherwise.
+ */
 MRB_API mrb_value mrb_hash_empty_p(mrb_state *mrb, mrb_value self);
 
 /*
  * Gets an array of values.
+ *
+ * Equivalent to:
+ *
+ *     hash.values
+ *
+ * @param mrb The mruby state reference.
+ * @param hash The target hash.
+ * @return An array with the values of the hash.
  */
 MRB_API mrb_value mrb_hash_values(mrb_state *mrb, mrb_value hash);
 
 /*
  * Clears the hash.
+ *
+ * Equivalent to:
+ *
+ *     hash.clear
+ *
+ * @param mrb The mruby state reference.
+ * @param hash The target hash.
+ * @return The hash
  */
 MRB_API mrb_value mrb_hash_clear(mrb_state *mrb, mrb_value hash);
 
diff --git a/include/mruby/istruct.h b/include/mruby/istruct.h
new file mode 100644
index 000000000..293a13788
--- /dev/null
+++ b/include/mruby/istruct.h
@@ -0,0 +1,47 @@
+/*
+** mruby/instruct.h - Inline structures
+**
+** See Copyright Notice in mruby.h
+*/
+
+#ifndef MRUBY_ISTRUCT_H
+#define MRUBY_ISTRUCT_H
+
+#include "common.h"
+#include <string.h>
+
+/**
+ * Inline structures that fit in RVALUE
+ *
+ * They cannot have finalizer, and cannot have instance variables.
+ */
+MRB_BEGIN_DECL
+
+#define ISTRUCT_DATA_SIZE (sizeof(void*) * 3)
+
+struct RIstruct {
+  MRB_OBJECT_HEADER;
+  char inline_data[ISTRUCT_DATA_SIZE];
+};
+
+#define RISTRUCT(obj)         ((struct RIstruct*)(mrb_ptr(obj)))
+#define ISTRUCT_PTR(obj)      (RISTRUCT(obj)->inline_data)
+
+MRB_INLINE mrb_int mrb_istruct_size()
+{
+  return ISTRUCT_DATA_SIZE;
+}
+
+MRB_INLINE void* mrb_istruct_ptr(mrb_value object)
+{
+  return ISTRUCT_PTR(object);
+}
+
+MRB_INLINE void mrb_istruct_copy(mrb_value dest, mrb_value src)
+{
+  memcpy(ISTRUCT_PTR(dest), ISTRUCT_PTR(src), ISTRUCT_DATA_SIZE);
+}
+
+MRB_END_DECL
+
+#endif /* MRUBY_ISTRUCT_H */
diff --git a/include/mruby/value.h b/include/mruby/value.h
index 4330b9441..6b29ab273 100644
--- a/include/mruby/value.h
+++ b/include/mruby/value.h
@@ -116,7 +116,8 @@ enum mrb_vtype {
   MRB_TT_ENV,         /*  20 */
   MRB_TT_DATA,        /*  21 */
   MRB_TT_FIBER,       /*  22 */
-  MRB_TT_MAXDEFINE    /*  23 */
+  MRB_TT_ISTRUCT,     /*  23 */
+  MRB_TT_MAXDEFINE    /*  24 */
 };
 
 #include <mruby/object.h>