Merge pull request #4636 from davidsiaw/doxygen

Generate doxygen docs for mruby

28 files changed, 113 insertions, 89 deletions

diff --git a/include/mruby.h b/include/mruby.h
index b1b983f52..87ccd8c05 100644
--- a/include/mruby.h
+++ b/include/mruby.h
@@ -25,6 +25,10 @@
 ** [ MIT license: http://www.opensource.org/licenses/mit-license.php ]
 */
 
+/**
+ * @file mruby.h
+ */
+
 #ifndef MRUBY_H
 #define MRUBY_H
 
@@ -97,11 +101,14 @@ MRB_BEGIN_DECL
 typedef uint8_t mrb_code;
 
 /**
- * Required arguments signature type.
+ * \class mrb_aspec
+ *
+ * Specifies the number of arguments a function takes
+ *
+ * Example: `MRB_ARGS_REQ(2) | MRB_ARGS_OPT(1)` for a method that expects 2..3 arguments
  */
 typedef uint32_t mrb_aspec;
 
-
 struct mrb_irep;
 struct mrb_state;
 
diff --git a/include/mruby/array.h b/include/mruby/array.h
index f8561d136..dde9f80cb 100644
--- a/include/mruby/array.h
+++ b/include/mruby/array.h
@@ -1,5 +1,5 @@
-/*
-** mruby/array.h - Array class
+/**
+** @file mruby/array.h - Array class
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/boxing_nan.h b/include/mruby/boxing_nan.h
index ff6f6082d..702fa13fb 100644
--- a/include/mruby/boxing_nan.h
+++ b/include/mruby/boxing_nan.h
@@ -1,5 +1,5 @@
-/*
-** mruby/boxing_nan.h - nan boxing mrb_value definition
+/**
+** @file mruby/boxing_nan.h - nan boxing mrb_value definition
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/boxing_no.h b/include/mruby/boxing_no.h
index 86ce64555..152471913 100644
--- a/include/mruby/boxing_no.h
+++ b/include/mruby/boxing_no.h
@@ -1,5 +1,5 @@
-/*
-** mruby/boxing_no.h - unboxed mrb_value definition
+/**
+** @file mruby/boxing_no.h - unboxed mrb_value definition
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/boxing_word.h b/include/mruby/boxing_word.h
index f16968a1f..bd8105496 100644
--- a/include/mruby/boxing_word.h
+++ b/include/mruby/boxing_word.h
@@ -1,5 +1,5 @@
-/*
-** mruby/boxing_word.h - word boxing mrb_value definition
+/**
+** @file mruby/boxing_word.h - word boxing mrb_value definition
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/class.h b/include/mruby/class.h
index 169e1327b..7c925f3b3 100644
--- a/include/mruby/class.h
+++ b/include/mruby/class.h
@@ -1,5 +1,5 @@
-/*
-** mruby/class.h - Class class
+/**
+** @file mruby/class.h - Class class
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/common.h b/include/mruby/common.h
index dc9e3acc5..45ab71ef5 100644
--- a/include/mruby/common.h
+++ b/include/mruby/common.h
@@ -1,5 +1,5 @@
-/*
-**"common.h - mruby common platform definition"
+/**
+** @file common.h - mruby common platform definition"
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/compile.h b/include/mruby/compile.h
index 3b25ff526..ac9a9892a 100644
--- a/include/mruby/compile.h
+++ b/include/mruby/compile.h
@@ -1,5 +1,5 @@
-/*
-** mruby/compile.h - mruby parser
+/**
+** @file mruby/compile.h - mruby parser
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/data.h b/include/mruby/data.h
index 54466dcd6..35ec2c25b 100644
--- a/include/mruby/data.h
+++ b/include/mruby/data.h
@@ -1,5 +1,5 @@
-/*
-** mruby/data.h - Data class
+/**
+** @file mruby/data.h - Data class
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/debug.h b/include/mruby/debug.h
index e08c47cfc..f28dd645a 100644
--- a/include/mruby/debug.h
+++ b/include/mruby/debug.h
@@ -1,5 +1,5 @@
-/*
-** mruby/debug.h - mruby debug info
+/**
+** @file mruby/debug.h - mruby debug info
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/dump.h b/include/mruby/dump.h
index 65ed8af9d..46c3b63ce 100644
--- a/include/mruby/dump.h
+++ b/include/mruby/dump.h
@@ -1,5 +1,5 @@
-/*
-** mruby/dump.h - mruby binary dumper (mrbc binary format)
+/**
+** @file mruby/dump.h - mruby binary dumper (mrbc binary format)
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/error.h b/include/mruby/error.h
index 237c701ad..b795bdf4c 100644
--- a/include/mruby/error.h
+++ b/include/mruby/error.h
@@ -1,5 +1,5 @@
-/*
-** mruby/error.h - Exception class
+/**
+** @file mruby/error.h - Exception class
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/gc.h b/include/mruby/gc.h
index 2a3ff4182..4d9fb60eb 100644
--- a/include/mruby/gc.h
+++ b/include/mruby/gc.h
@@ -1,5 +1,5 @@
-/*
-** mruby/gc.h - garbage collector for mruby
+/**
+** @file mruby/gc.h - garbage collector for mruby
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/hash.h b/include/mruby/hash.h
index 7e2ed5596..734a8c3b5 100644
--- a/include/mruby/hash.h
+++ b/include/mruby/hash.h
@@ -1,5 +1,5 @@
-/*
-** mruby/hash.h - Hash class
+/**
+** @file mruby/hash.h - Hash class
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/irep.h b/include/mruby/irep.h
index 2989e0647..4393129c7 100644
--- a/include/mruby/irep.h
+++ b/include/mruby/irep.h
@@ -1,5 +1,5 @@
-/*
-** mruby/irep.h - mrb_irep structure
+/**
+** @file mruby/irep.h - mrb_irep structure
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/istruct.h b/include/mruby/istruct.h
index 23c9bfa36..45b1fadae 100644
--- a/include/mruby/istruct.h
+++ b/include/mruby/istruct.h
@@ -1,5 +1,5 @@
-/*
-** mruby/istruct.h - Inline structures
+/**
+** @file mruby/istruct.h - Inline structures
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/khash.h b/include/mruby/khash.h
index 9c40c6b80..c00357061 100644
--- a/include/mruby/khash.h
+++ b/include/mruby/khash.h
@@ -1,5 +1,5 @@
-/*
-** mruby/khash.c - Hash for mruby
+/**
+** @file mruby/khash.h - Hash for mruby
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/numeric.h b/include/mruby/numeric.h
index 39f6773d9..a176d96cd 100644
--- a/include/mruby/numeric.h
+++ b/include/mruby/numeric.h
@@ -1,5 +1,5 @@
-/*
-** mruby/numeric.h - Numeric, Integer, Float, Fixnum class
+/**
+** @file mruby/numeric.h - Numeric, Integer, Float, Fixnum class
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/object.h b/include/mruby/object.h
index 373e3bec7..48dcc4977 100644
--- a/include/mruby/object.h
+++ b/include/mruby/object.h
@@ -1,5 +1,5 @@
-/*
-** mruby/object.h - mruby object definition
+/**
+** @file mruby/object.h - mruby object definition
 **
 ** See Copyright Notice in mruby.h
 */
@@ -8,15 +8,14 @@
 #define MRUBY_OBJECT_H
 
 #define MRB_OBJECT_HEADER \
-  enum mrb_vtype tt:8;\
-  uint32_t color:3;\
-  uint32_t flags:21;\
-  struct RClass *c;\
+  enum mrb_vtype tt:8;    \
+  uint32_t color:3;       \
+  uint32_t flags:21;      \
+  struct RClass *c;       \
   struct RBasic *gcnext
 
 #define MRB_FLAG_TEST(obj, flag) ((obj)->flags & (flag))
 
-
 struct RBasic {
   MRB_OBJECT_HEADER;
 };
diff --git a/include/mruby/opcode.h b/include/mruby/opcode.h
index d513ca472..95e6736a4 100644
--- a/include/mruby/opcode.h
+++ b/include/mruby/opcode.h
@@ -1,5 +1,5 @@
-/*
-** mruby/opcode.h - RiteVM operation codes
+/**
+** @file mruby/opcode.h - RiteVM operation codes
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/proc.h b/include/mruby/proc.h
index a8b16db1d..d6459f8bf 100644
--- a/include/mruby/proc.h
+++ b/include/mruby/proc.h
@@ -1,5 +1,5 @@
-/*
-** mruby/proc.h - Proc class
+/**
+** @file mruby/proc.h - Proc class
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/range.h b/include/mruby/range.h
index 500a941d5..fea700c24 100644
--- a/include/mruby/range.h
+++ b/include/mruby/range.h
@@ -1,5 +1,5 @@
-/*
-** mruby/range.h - Range class
+/**
+** @file mruby/range.h - Range class
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/re.h b/include/mruby/re.h
index 1d09d06c9..2d48019cf 100644
--- a/include/mruby/re.h
+++ b/include/mruby/re.h
@@ -1,5 +1,5 @@
-/*
-** mruby/re.h - Regexp class
+/**
+** @file mruby/re.h - Regexp class
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/string.h b/include/mruby/string.h
index 51510457d..ab29be421 100644
--- a/include/mruby/string.h
+++ b/include/mruby/string.h
@@ -1,5 +1,5 @@
-/*
-** mruby/string.h - String class
+/**
+** @file mruby/string.h - String class
 **
 ** See Copyright Notice in mruby.h
 */
@@ -90,7 +90,7 @@ struct RString {
 #define RSTR_POOL_P(s) ((s)->flags & MRB_STR_POOL)
 #define RSTR_SET_POOL_FLAG(s) ((s)->flags |= MRB_STR_POOL)
 
-/*
+/**
  * Returns a pointer from a Ruby string
  */
 #define mrb_str_ptr(s)       ((struct RString*)(mrb_ptr(s)))
@@ -121,13 +121,13 @@ MRB_API void mrb_str_modify(mrb_state *mrb, struct RString *s);
 /* mrb_str_modify() with keeping ASCII flag if set */
 MRB_API void mrb_str_modify_keep_ascii(mrb_state *mrb, struct RString *s);
 
-/*
+/**
  * Finds the index of a substring in a string
  */
 MRB_API mrb_int mrb_str_index(mrb_state*, mrb_value, const char*, mrb_int, mrb_int);
 #define mrb_str_index_lit(mrb, str, lit, off) mrb_str_index(mrb, str, lit, mrb_strlen_lit(lit), off);
 
-/*
+/**
  * Appends self to other. Returns self as a concatenated string.
  *
  *
@@ -174,7 +174,7 @@ MRB_API mrb_int mrb_str_index(mrb_state*, mrb_value, const char*, mrb_int, mrb_i
  */
 MRB_API void mrb_str_concat(mrb_state*, mrb_value, mrb_value);
 
-/*
+/**
  * Adds two strings together.
  *
  *
@@ -228,7 +228,7 @@ MRB_API void mrb_str_concat(mrb_state*, mrb_value, mrb_value);
  */
 MRB_API mrb_value mrb_str_plus(mrb_state*, mrb_value, mrb_value);
 
-/*
+/**
  * Converts pointer into a Ruby string.
  *
  * @param [mrb_state] mrb The current mruby state.
@@ -237,7 +237,7 @@ MRB_API mrb_value mrb_str_plus(mrb_state*, mrb_value, mrb_value);
  */
 MRB_API mrb_value mrb_ptr_to_str(mrb_state *, void*);
 
-/*
+/**
  * Returns an object as a Ruby string.
  *
  * @param [mrb_state] mrb The current mruby state.
@@ -246,7 +246,7 @@ MRB_API mrb_value mrb_ptr_to_str(mrb_state *, void*);
  */
 MRB_API mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj);
 
-/*
+/**
  * Resizes the string's length. Returns the amount of characters
  * in the specified by len.
  *
@@ -286,7 +286,7 @@ MRB_API mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj);
  */
 MRB_API mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len);
 
-/*
+/**
  * Returns a sub string.
  *
  *  Example:
@@ -329,7 +329,7 @@ MRB_API mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len);
  */
 MRB_API mrb_value mrb_str_substr(mrb_state *mrb, mrb_value str, mrb_int beg, mrb_int len);
 
-/*
+/**
  * Returns a Ruby string type.
  *
  *
@@ -355,7 +355,7 @@ MRB_API const char *mrb_string_value_ptr(mrb_state *mrb, mrb_value str);
 /* obslete: use RSTRING_LEN() */
 MRB_API mrb_int mrb_string_value_len(mrb_state *mrb, mrb_value str);
 
-/*
+/**
  * Duplicates a string object.
  *
  *
@@ -365,7 +365,7 @@ MRB_API mrb_int mrb_string_value_len(mrb_state *mrb, mrb_value str);
  */
 MRB_API mrb_value mrb_str_dup(mrb_state *mrb, mrb_value str);
 
-/*
+/**
  * Returns a symbol from a passed in Ruby string.
  *
  * @param [mrb_state] mrb The current mruby state.
@@ -379,13 +379,13 @@ MRB_API mrb_value mrb_cstr_to_inum(mrb_state *mrb, const char *s, mrb_int base,
 MRB_API double mrb_str_to_dbl(mrb_state *mrb, mrb_value str, mrb_bool badcheck);
 MRB_API double mrb_cstr_to_dbl(mrb_state *mrb, const char *s, mrb_bool badcheck);
 
-/*
+/**
  * Returns a converted string type.
  * For type checking, non converting `mrb_to_str` is recommended.
  */
 MRB_API mrb_value mrb_str_to_str(mrb_state *mrb, mrb_value str);
 
-/*
+/**
  * Returns true if the strings match and false if the strings don't match.
  *
  * @param [mrb_state] mrb The current mruby state.
@@ -395,8 +395,8 @@ MRB_API mrb_value mrb_str_to_str(mrb_state *mrb, mrb_value str);
  */
 MRB_API mrb_bool mrb_str_equal(mrb_state *mrb, mrb_value str1, mrb_value str2);
 
-/*
- * Returns a concated string comprised of a Ruby string and a C string.
+/**
+ * Returns a concatenated string comprised of a Ruby string and a C string.
  *
  * @param [mrb_state] mrb The current mruby state.
  * @param [mrb_value] str Ruby string.
@@ -407,8 +407,8 @@ MRB_API mrb_bool mrb_str_equal(mrb_state *mrb, mrb_value str1, mrb_value str2);
  */
 MRB_API mrb_value mrb_str_cat(mrb_state *mrb, mrb_value str, const char *ptr, size_t len);
 
-/*
- * Returns a concated string comprised of a Ruby string and a C string.
+/**
+ * Returns a concatenated string comprised of a Ruby string and a C string.
  *
  * @param [mrb_state] mrb The current mruby state.
  * @param [mrb_value] str Ruby string.
@@ -420,17 +420,17 @@ MRB_API mrb_value mrb_str_cat_cstr(mrb_state *mrb, mrb_value str, const char *pt
 MRB_API mrb_value mrb_str_cat_str(mrb_state *mrb, mrb_value str, mrb_value str2);
 #define mrb_str_cat_lit(mrb, str, lit) mrb_str_cat(mrb, str, lit, mrb_strlen_lit(lit))
 
-/*
+/**
  * Adds str2 to the end of str1.
  */
 MRB_API mrb_value mrb_str_append(mrb_state *mrb, mrb_value str, mrb_value str2);
 
-/*
+/**
  * Returns 0 if both Ruby strings are equal. Returns a value < 0 if Ruby str1 is less than Ruby str2. Returns a value > 0 if Ruby str2 is greater than Ruby str1.
  */
 MRB_API int mrb_str_cmp(mrb_state *mrb, mrb_value str1, mrb_value str2);
 
-/*
+/**
  * Returns a newly allocated C string from a Ruby string.
  * This is an utility function to pass a Ruby string to C library functions.
  *
@@ -451,7 +451,7 @@ mrb_value mrb_str_pool(mrb_state *mrb, mrb_value str);
 uint32_t mrb_str_hash(mrb_state *mrb, mrb_value str);
 mrb_value mrb_str_dump(mrb_state *mrb, mrb_value str);
 
-/*
+/**
  * Returns a printable version of str, surrounded by quote marks, with special characters escaped.
  */
 mrb_value mrb_str_inspect(mrb_state *mrb, mrb_value str);
diff --git a/include/mruby/throw.h b/include/mruby/throw.h
index 4a1fd8d60..1f1298d7d 100644
--- a/include/mruby/throw.h
+++ b/include/mruby/throw.h
@@ -1,5 +1,5 @@
-/*
-** mruby/throw.h - mruby exception throwing handler
+/**
+** @file mruby/throw.h - mruby exception throwing handler
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/value.h b/include/mruby/value.h
index be3dd397f..2ba0b3587 100644
--- a/include/mruby/value.h
+++ b/include/mruby/value.h
@@ -1,5 +1,5 @@
-/*
-** mruby/value.h - mruby value definitions
+/**
+** @file mruby/value.h - mruby value definitions
 **
 ** See Copyright Notice in mruby.h
 */
@@ -9,12 +9,27 @@
 
 #include "common.h"
 
-/**
+/*
  * MRuby Value definition functions and macros.
  */
 MRB_BEGIN_DECL
 
+/**
+ * @class mrb_sym
+ * @brief mruby Symbol
+ * 
+ * You can create an mrb_sym by simply using mrb_str_intern() or mrb_intern_cstr()
+ */
 typedef uint32_t mrb_sym;
+
+/**
+ * @class mrb_bool
+ * @brief mruby Boolean
+ *
+ * Used internally to represent boolean. Can be TRUE or FALSE.
+ * Not to be confused with Ruby's boolean classes, which can be 
+ * obtained using mrb_false_value() and mrb_true_value()
+ */
 typedef uint8_t mrb_bool;
 struct mrb_state;
 
@@ -178,8 +193,10 @@ typedef void mrb_value;
 #define mrb_exception_p(o) (mrb_type(o) == MRB_TT_EXCEPTION)
 #define mrb_test(o)   mrb_bool(o)
 
-/*
+/**
  * Returns a float in Ruby.
+ *
+ * Takes a float and boxes it into an mrb_value
  */
 #ifndef MRB_WITHOUT_FLOAT
 MRB_INLINE mrb_value mrb_float_value(struct mrb_state *mrb, mrb_float f)
@@ -200,8 +217,10 @@ mrb_cptr_value(struct mrb_state *mrb, void *p)
   return v;
 }
 
-/*
+/**
  * Returns a fixnum in Ruby.
+ *
+ * Takes an integer and boxes it into an mrb_value
  */
 MRB_INLINE mrb_value mrb_fixnum_value(mrb_int i)
 {
@@ -228,8 +247,7 @@ mrb_obj_value(void *p)
   return v;
 }
 
-
-/*
+/**
  * Get a nil mrb_value object.
  *
  * @return
@@ -242,7 +260,7 @@ MRB_INLINE mrb_value mrb_nil_value(void)
   return v;
 }
 
-/*
+/**
  * Returns false in Ruby.
  */
 MRB_INLINE mrb_value mrb_false_value(void)
@@ -252,7 +270,7 @@ MRB_INLINE mrb_value mrb_false_value(void)
   return v;
 }
 
-/*
+/**
  * Returns true in Ruby.
  */
 MRB_INLINE mrb_value mrb_true_value(void)
diff --git a/include/mruby/variable.h b/include/mruby/variable.h
index ff01e5cc8..8ae33304d 100644
--- a/include/mruby/variable.h
+++ b/include/mruby/variable.h
@@ -1,5 +1,5 @@
-/*
-** mruby/variable.h - mruby variables
+/**
+** @file mruby/variable.h - mruby variables
 **
 ** See Copyright Notice in mruby.h
 */
diff --git a/include/mruby/version.h b/include/mruby/version.h
index 206078df0..3140ea481 100644
--- a/include/mruby/version.h
+++ b/include/mruby/version.h
@@ -1,5 +1,5 @@
-/*
-** mruby/version.h - mruby version definition
+/**
+** @file mruby/version.h - mruby version definition
 **
 ** See Copyright Notice in mruby.h
 */