Merge pull request #4636 from davidsiaw/doxygen

Generate doxygen docs for mruby

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
 */

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
 */

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
 */

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
 */

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
 */

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
 */

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
 */

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
 */

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
 */

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
 */

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
 */

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
 */

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
 */

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
 */

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
 */

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
 */

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
 */

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;
 };

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
 */

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
 */

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
 */

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
 */

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);

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
 */

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)

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
 */

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
 */