Merge pull request #2984 from sagmor/yard

Simpler documentation

20 files changed, 278 insertions, 207 deletions

diff --git a/include/mruby.h b/include/mruby.h
index 6d34b241c..55d3c369d 100644
--- a/include/mruby.h
+++ b/include/mruby.h
@@ -38,9 +38,7 @@
 #include "mruby/version.h"
 
 /**
- * @file mruby.h
- * @defgroup mruby MRuby C API
- * @{
+ * MRuby C API entry point
  */
 MRB_BEGIN_DECL
 
@@ -56,13 +54,13 @@ struct mrb_irep;
 struct mrb_state;
 
 /**
- * Function pointer type of custom allocator used in @ref mrb_open_allocf.
+ * Function pointer type of custom allocator used in @see mrb_open_allocf.
  *
  * The function pointing it must behave similarly as realloc except:
  * - If ptr is NULL it must allocate new space.
  * - If s is NULL, ptr must be freed.
  *
- * See @ref mrb_default_allocf for the default implementation.
+ * See @see mrb_default_allocf for the default implementation.
  */
 typedef void* (*mrb_allocf) (struct mrb_state *mrb, void*, size_t, void *ud);
 
@@ -213,21 +211,25 @@ typedef mrb_value (*mrb_func_t)(mrb_state *mrb, mrb_value);
  * Defines a new class.
  *
  * If you're creating a gem it may look something like this:
- *  <pre>
- *    void mrb_example_gem_init(mrb_state* mrb) {
- *      struct RClass *example_class;
- *      example_class = mrb_define_class(mrb, "Example_Class", mrb->object_class);
- *    }
  *
- *    void mrb_example_gem_final(mrb_state* mrb) {
- *      //free(TheAnimals);
- *    }
- *  </pre>
+ *      !!!c
+ *      void mrb_example_gem_init(mrb_state* mrb) {
+ *              struct RClass *example_class;
+ *              example_class = mrb_define_class(mrb, "Example_Class", mrb->object_class);
+ *      }
  *
+ *      void mrb_example_gem_final(mrb_state* mrb) {
+ *              //free(TheAnimals);
+ *      }
+ *
+ * @param mrb The current mruby state.
  * @param name The name of the defined class
  * @param super The new class parent
+ * @return Reference to the newly defined class
+ * @see mrb_define_class_under
  */
 MRB_API struct RClass *mrb_define_class(mrb_state *mrb, const char *name, struct RClass *super);
+
 MRB_API struct RClass *mrb_define_module(mrb_state *, const char*);
 MRB_API mrb_value mrb_singleton_class(mrb_state*, mrb_value);
 MRB_API void mrb_include_module(mrb_state*, struct RClass*, struct RClass*);
@@ -238,6 +240,7 @@ MRB_API void mrb_prepend_module(mrb_state*, struct RClass*, struct RClass*);
  *
  * If you're creating a gem it may look something like this:
  *
+ *     !!!c
  *     mrb_value example_method(mrb_state* mrb, mrb_value self)
  *     {
  *          puts("Executing example command!");
@@ -249,15 +252,10 @@ MRB_API void mrb_prepend_module(mrb_state*, struct RClass*, struct RClass*);
  *           mrb_define_method(mrb, mrb->kernel_module, "example_method", example_method, MRB_ARGS_NONE());
  *     }
  *
- * @param mrb
- *      The MRuby state reference.
- * @param cla
- *      The class pointer where the method will be defined.
- * @param func
- *      The function pointer to the method definition.
- * @param aspec
- *      The method parameters declaration.
- *      See @ref mruby_mrb_aspec for details.
+ * @param mrb The MRuby state reference.
+ * @param cla The class pointer where the method will be defined.
+ * @param func The function pointer to the method definition.
+ * @param aspec The method parameters declaration.
  */
 MRB_API void mrb_define_method(mrb_state *mrb, struct RClass *cla, const char *name, mrb_func_t func, mrb_aspec aspec);
 
@@ -271,20 +269,15 @@ MRB_API void mrb_undef_class_method(mrb_state*, struct RClass*, const char*);
 /**
  * Initialize a new object instace of c class.
  *
- * @param mrb
- *      The current mruby state.
- * @param c
- *      Reference to the class of the new object.
- * @param argc
- *      Number of arguments in argv
- * @param argv
- *      Array of @ref mrb_value "mrb_values" to initialize the object
- * @returns
- *      The newly initialized object
+ * @param mrb The current mruby state.
+ * @param c Reference to the class of the new object.
+ * @param argc Number of arguments in argv
+ * @param argv Array of mrb_value to initialize the object
+ * @return The newly initialized object
  */
 MRB_API mrb_value mrb_obj_new(mrb_state *mrb, struct RClass *c, mrb_int argc, const mrb_value *argv);
 
-/** See @ref mrb_obj_new */
+/** @see mrb_obj_new */
 MRB_INLINE mrb_value mrb_class_new_instance(mrb_state *mrb, mrb_int argc, const mrb_value *argv, struct RClass *c)
 {
   return mrb_obj_new(mrb,c,argc,argv);
@@ -303,17 +296,20 @@ MRB_API mrb_value mrb_notimplement_m(mrb_state*, mrb_value);
 MRB_API mrb_value mrb_obj_dup(mrb_state *mrb, mrb_value obj);
 MRB_API mrb_value mrb_check_to_integer(mrb_state *mrb, mrb_value val, const char *method);
 MRB_API mrb_bool mrb_obj_respond_to(mrb_state *mrb, struct RClass* c, mrb_sym mid);
-MRB_API struct RClass * mrb_define_class_under(mrb_state *mrb, struct RClass *outer, const char *name, struct RClass *super);
-MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *outer, const char *name);
 
 /**
- * @defgroup mruby_mrb_aspec Required arguments declaration helpers.
- *
- * Helper functions to declare arguments requirements on methods declared by
- * \ref mrb_define_method and the like
+ * Defines a new class under a given module
  *
- * @{
+ * @param mrb The current mruby state.
+ * @param outer Reference to the module under which the new class will be defined
+ * @param name The name of the defined class
+ * @param super The new class parent
+ * @return Reference to the newly defined class
+ * @see mrb_define_class
  */
+MRB_API struct RClass * mrb_define_class_under(mrb_state *mrb, struct RClass *outer, const char *name, struct RClass *super);
+
+MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *outer, const char *name);
 
 /**
  * Function requires n arguments.
@@ -365,8 +361,6 @@ MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *o
  */
 #define MRB_ARGS_NONE()     ((mrb_aspec)0)
 
-/** @} */
-
 /**
  * Format specifiers for \ref mrb_get_args function
  *
@@ -400,14 +394,10 @@ typedef const char *mrb_args_format;
  * applied to received arguments.
  * Use it inside a function pointed by mrb_func_t.
  *
- * @param mrb
- *      The current MRuby state.
- * @param format
- *      is a list of format specifiers see @ref mrb_args_format
- * @param ...
- *      The passing variadic arguments must be a pointer of retrieving type.
- * @return
- *      the number of arguments retrieved.
+ * @param mrb The current MRuby state.
+ * @param format is a list of format specifiers see @ref mrb_args_format
+ * @param ... The passing variadic arguments must be a pointer of retrieving type.
+ * @return the number of arguments retrieved.
  */
 MRB_API mrb_int mrb_get_args(mrb_state *mrb, mrb_args_format format, ...);
 
@@ -469,7 +459,7 @@ char* mrb_locale_from_utf8(const char *p, size_t len);
 /**
  * Creates new mrb_state.
  *
- * @returns
+ * @return
  *      Pointer to the newly created mrb_state.
  */
 MRB_API mrb_state* mrb_open(void);
@@ -482,7 +472,7 @@ MRB_API mrb_state* mrb_open(void);
  * @param ud
  *      User data will be passed to custom allocator f.
  *      If user data isn't required just pass NULL.
- * @returns
+ * @return
  *      Pointer to the newly created mrb_state.
  */
 MRB_API mrb_state* mrb_open_allocf(mrb_allocf f, void *ud);
@@ -496,7 +486,7 @@ MRB_API mrb_state* mrb_open_allocf(mrb_allocf f, void *ud);
  * @param ud
  *      User data will be passed to custom allocator f.
  *      If user data isn't required just pass NULL.
- * @returns
+ * @return
  *      Pointer to the newly created mrb_state.
  */
 MRB_API mrb_state* mrb_open_core(mrb_allocf f, void *ud);
@@ -676,7 +666,6 @@ MRB_API void mrb_show_copyright(mrb_state *mrb);
 
 MRB_API mrb_value mrb_format(mrb_state *mrb, const char *format, ...);
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_H */
diff --git a/include/mruby/array.h b/include/mruby/array.h
index e716c883d..16f5acee2 100644
--- a/include/mruby/array.h
+++ b/include/mruby/array.h
@@ -9,11 +9,8 @@
 
 #include "mruby/common.h"
 
-/**
- * @file mruby/array.h
- * @defgroup mruby_array Array class
- * @ingroup mruby
- * @{
+/*
+ * Array class
  */
 MRB_BEGIN_DECL
 
@@ -49,89 +46,74 @@ void mrb_ary_decref(mrb_state*, mrb_shared_array*);
 MRB_API void mrb_ary_modify(mrb_state*, struct RArray*);
 MRB_API mrb_value mrb_ary_new_capa(mrb_state*, mrb_int);
 
-/**
+/*
  * Initializes a new array.
  *
  * Equivalent to:
  *
  *      Array.new
  *
- * @param mrb
- *      The MRuby state reference.
- * @returns
- *      The initialized array
+ * @param mrb The mruby state reference.
+ * @return The initialized array
  */
 MRB_API mrb_value mrb_ary_new(mrb_state *mrb);
+
 MRB_API mrb_value mrb_ary_new_from_values(mrb_state *mrb, mrb_int size, const mrb_value *vals);
 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);
 
-/**
+/*
  * Pushes value into array.
  *
  * Equivalent to:
  *
  *      ary << value
  *
- * @param mrb
- *      The MRuby state reference.
- * @param ary
- *      The array in which the value will be pushed
- * @param value
- *      The value to be pushed into array
+ * @param mrb The mruby state reference.
+ * @param ary The array in which the value will be pushed
+ * @param value The value to be pushed into array
  */
 MRB_API void mrb_ary_push(mrb_state *mrb, mrb_value array, mrb_value value);
 
-/**
+/*
  * Pops the last element from the array.
  *
  * Equivalent to:
  *
  *      ary.pop
  *
- * @param mrb
- *      The MRuby state reference.
- * @param ary
- *      The array from which the value will be poped.
- * @returns
- *      The poped value.
+ * @param mrb The mruby state reference.
+ * @param ary The array from which the value will be poped.
+ * @return The poped value.
  */
 MRB_API mrb_value mrb_ary_pop(mrb_state *mrb, mrb_value ary);
 
-/**
+/*
  * Returns a reference to an element of the array on the given index.
  *
  * Equivalent to:
  *
  *      ary[n]
  *
- * @param mrb
- *      The MRuby state reference.
- * @param ary
- *      The target array.
- * @param n
- *      The array index being referenced
- * @returns
- *      The referenced value.
+ * @param mrb The mruby state reference.
+ * @param ary The target array.
+ * @param n The array index being referenced
+ * @return The referenced value.
  */
 MRB_API mrb_value mrb_ary_ref(mrb_state *mrb, mrb_value ary, mrb_int n);
 
-/**
+/*
  * Sets a value on an array at the given index
  *
  * Equivalent to:
  *
  *      ary[n] = val
  *
- * @param mrb
- *      The MRuby state reference.
- * @param ary
- *      The target array.
- * @param n
- *      The array index being referenced.
- * @param val
- *      The value being setted.
+ * @param mrb The mruby state reference.
+ * @param ary The target array.
+ * @param n The array index being referenced.
+ * @param val The value being setted.
  */
 MRB_API void mrb_ary_set(mrb_state *mrb, mrb_value ary, mrb_int n, mrb_value val);
 
@@ -152,7 +134,6 @@ mrb_ary_len(mrb_state *mrb, mrb_value ary)
   return RARRAY_LEN(ary);
 }
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_ARRAY_H */
diff --git a/include/mruby/class.h b/include/mruby/class.h
index 35edce86c..09565ec08 100644
--- a/include/mruby/class.h
+++ b/include/mruby/class.h
@@ -10,10 +10,7 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/class.h
- * @defgroup mruby_class Class class
- * @ingroup mruby
- * @{
+ * Class class
  */
 MRB_BEGIN_DECL
 
@@ -87,7 +84,6 @@ void mrb_gc_mark_mt(mrb_state*, struct RClass*);
 size_t mrb_gc_mark_mt_size(mrb_state*, struct RClass*);
 void mrb_gc_free_mt(mrb_state*, struct RClass*);
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_CLASS_H */
diff --git a/include/mruby/common.h b/include/mruby/common.h
index 01e558291..e7841f38f 100644
--- a/include/mruby/common.h
+++ b/include/mruby/common.h
@@ -7,12 +7,6 @@
 #ifndef MRUBY_COMMON_H
 #define MRUBY_COMMON_H
 
-/**
- * @file mruby/common.h
- * @defgroup mruby_common Shared compiler macros
- * @ingroup mruby
- * @{
- */
 
 #ifdef __cplusplus
 # define MRB_BEGIN_DECL extern "C" {
@@ -24,6 +18,11 @@
 # define MRB_END_DECL
 #endif
 
+/**
+ * Shared compiler macros
+ */
+MRB_BEGIN_DECL
+
 /** Declare a function that never returns. */
 #if __STDC_VERSION__ >= 201112L
 # define mrb_noreturn _Noreturn
@@ -63,6 +62,6 @@
 # define MRB_API extern
 #endif
 
-/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_COMMON_H */
diff --git a/include/mruby/compile.h b/include/mruby/compile.h
index c482ddf69..637b469a8 100644
--- a/include/mruby/compile.h
+++ b/include/mruby/compile.h
@@ -10,10 +10,7 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/compile.h
- * @defgroup mruby_compile Compiler
- * @ingroup mruby
- * @{
+ * MRuby Compiler
  */
 MRB_BEGIN_DECL
 
diff --git a/include/mruby/data.h b/include/mruby/data.h
index c68b050f7..472829c57 100644
--- a/include/mruby/data.h
+++ b/include/mruby/data.h
@@ -10,13 +10,9 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/data.h
- * @defgroup mruby_data Custom C wrapped data.
+ * Custom C wrapped data.
  *
  * Defining Ruby wrappers around native objects.
- *
- * @ingroup mruby
- * @{
  */
 MRB_BEGIN_DECL
 
@@ -74,7 +70,6 @@ mrb_data_init(mrb_value v, void *ptr, const mrb_data_type *type)
   DATA_TYPE(v) = type;
 }
 
-/** @} */
 MRB_END_DECL
 
 #endif /* MRUBY_DATA_H */
diff --git a/include/mruby/debug.h b/include/mruby/debug.h
index 94ef1e723..553968a86 100644
--- a/include/mruby/debug.h
+++ b/include/mruby/debug.h
@@ -10,10 +10,7 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/debug.h
- * @defgroup mruby_debug Debugging.
- * @ingroup mruby
- * @{
+ * MRuby Debugging.
  */
 MRB_BEGIN_DECL
 
@@ -64,7 +61,6 @@ MRB_API mrb_irep_debug_info_file *mrb_debug_info_append_file(
 MRB_API mrb_irep_debug_info *mrb_debug_info_alloc(mrb_state *mrb, mrb_irep *irep);
 MRB_API void mrb_debug_info_free(mrb_state *mrb, mrb_irep_debug_info *d);
 
-/** @} */
 MRB_END_DECL
 
 #endif /* MRUBY_DEBUG_H */
diff --git a/include/mruby/dump.h b/include/mruby/dump.h
index 293122f9a..6a36cbce6 100644
--- a/include/mruby/dump.h
+++ b/include/mruby/dump.h
@@ -12,10 +12,7 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/dump.h
- * @defgroup mruby_dump Dumping compiled mruby script.
- * @ingroup mruby
- * @{
+ * Dumping compiled mruby script.
  */
 MRB_BEGIN_DECL
 
@@ -190,7 +187,6 @@ bin_to_uint8(const uint8_t *bin)
   return (uint8_t)bin[0];
 }
 
-/** @} */
 MRB_END_DECL
 
 /** @internal crc.c */
diff --git a/include/mruby/error.h b/include/mruby/error.h
index 347ca7738..8b6430137 100644
--- a/include/mruby/error.h
+++ b/include/mruby/error.h
@@ -10,10 +10,7 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/error.h
- * @defgroup mruby_error Error handling.
- * @ingroup mruby
- * @{
+ * MRuby error handling.
  */
 MRB_BEGIN_DECL
 
@@ -45,7 +42,6 @@ MRB_API mrb_value mrb_rescue_exceptions(mrb_state *mrb, mrb_func_t body, mrb_val
                                         mrb_func_t rescue, mrb_value r_data,
                                         mrb_int len, struct RClass **classes);
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_ERROR_H */
diff --git a/include/mruby/gc.h b/include/mruby/gc.h
index a9187bb56..0b33617de 100644
--- a/include/mruby/gc.h
+++ b/include/mruby/gc.h
@@ -10,10 +10,7 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/gc.h
- * @defgroup mruby_gc Uncommon memory management stuffs.
- * @ingroup mruby
- * @{
+ * Uncommon memory management stuffs.
  */
 MRB_BEGIN_DECL
 
@@ -21,7 +18,6 @@ typedef void (mrb_each_object_callback)(mrb_state *mrb, struct RBasic *obj, void
 void mrb_objspace_each_objects(mrb_state *mrb, mrb_each_object_callback *callback, void *data);
 MRB_API void mrb_free_context(mrb_state *mrb, struct mrb_context *c);
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_GC_H */
diff --git a/include/mruby/hash.h b/include/mruby/hash.h
index 1f69b4215..542986c92 100644
--- a/include/mruby/hash.h
+++ b/include/mruby/hash.h
@@ -10,10 +10,7 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/hash.h
- * @defgroup mruby_hash Hash class
- * @ingroup mruby
- * @{
+ * Hash class
  */
 MRB_BEGIN_DECL
 
@@ -27,15 +24,39 @@ struct RHash {
 #define mrb_hash_value(p)  mrb_obj_value((void*)(p))
 
 MRB_API mrb_value mrb_hash_new_capa(mrb_state*, int);
+
+/*
+ * Initializes a new hash.
+ */
 MRB_API mrb_value mrb_hash_new(mrb_state *mrb);
 
+/*
+ * Sets a keys and values to hashes.
+ */
 MRB_API void mrb_hash_set(mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value val);
+
+/*
+ * Gets a value from a key.
+ */
 MRB_API mrb_value mrb_hash_get(mrb_state *mrb, mrb_value hash, mrb_value key);
+
 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.
+ */
 MRB_API mrb_value mrb_hash_delete_key(mrb_state *mrb, mrb_value hash, mrb_value key);
+
+/*
+ * Gets an array of keys.
+ */
 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);
 MRB_API mrb_value mrb_hash_empty_p(mrb_state *mrb, mrb_value self);
+
+/*
+ * Clears the hash.
+ */
 MRB_API mrb_value mrb_hash_clear(mrb_state *mrb, mrb_value hash);
 
 /* RHASH_TBL allocates st_table if not available. */
@@ -53,7 +74,6 @@ void mrb_gc_mark_hash(mrb_state*, struct RHash*);
 size_t mrb_gc_mark_hash_size(mrb_state*, struct RHash*);
 void mrb_gc_free_hash(mrb_state*, struct RHash*);
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_HASH_H */
diff --git a/include/mruby/irep.h b/include/mruby/irep.h
index 1f08f44fa..aaf8bd0ef 100644
--- a/include/mruby/irep.h
+++ b/include/mruby/irep.h
@@ -11,10 +11,7 @@
 #include "mruby/compile.h"
 
 /**
- * @file mruby/irep.h
- * @defgroup mruby_irep Compiled mruby scripts.
- * @ingroup mruby
- * @{
+ * Compiled mruby scripts.
  */
 MRB_BEGIN_DECL
 
@@ -58,7 +55,6 @@ void mrb_irep_free(mrb_state*, struct mrb_irep*);
 void mrb_irep_incref(mrb_state*, struct mrb_irep*);
 void mrb_irep_decref(mrb_state*, struct mrb_irep*);
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_IREP_H */
diff --git a/include/mruby/khash.h b/include/mruby/khash.h
index 36119bfcf..4331ef137 100644
--- a/include/mruby/khash.h
+++ b/include/mruby/khash.h
@@ -13,10 +13,7 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/khash.h
- * @defgroup mruby_khash khash definitions used in mruby's hash table.
- * @ingroup mruby
- * @{
+ * khash definitions used in mruby's hash table.
  */
 MRB_BEGIN_DECL
 
@@ -272,7 +269,6 @@ static inline khint_t __ac_X31_hash_string(const char *s)
 
 typedef const char *kh_cstr_t;
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_KHASH_H */
diff --git a/include/mruby/numeric.h b/include/mruby/numeric.h
index a7aa6c81b..6366e8674 100644
--- a/include/mruby/numeric.h
+++ b/include/mruby/numeric.h
@@ -10,13 +10,9 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/numeric.h
- * @defgroup mruby_numeric Numeric class and it's sub-classes.
+ * Numeric class and it's sub-classes.
  *
- * Numeric, Integer, Float, Fixnum classes
- *
- * @ingroup mruby
- * @{
+ * Integer, Float and Fixnum
  */
 MRB_BEGIN_DECL
 
@@ -113,7 +109,6 @@ mrb_int_sub_overflow(mrb_int minuend, mrb_int subtrahend, mrb_int *difference)
 #undef MRB_UINT_MAKE
 #undef MRB_UINT_MAKE2
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_NUMERIC_H */
diff --git a/include/mruby/proc.h b/include/mruby/proc.h
index 6b8d3cd9f..85096fe5e 100644
--- a/include/mruby/proc.h
+++ b/include/mruby/proc.h
@@ -11,10 +11,7 @@
 #include "mruby/irep.h"
 
 /**
- * @file mruby/proc.h
- * @defgroup mruby_proc Proc class
- * @ingroup mruby
- * @{
+ * Proc class
  */
 MRB_BEGIN_DECL
 
@@ -74,7 +71,6 @@ MRB_API mrb_value mrb_proc_cfunc_env_get(mrb_state*, mrb_int);
 #include "mruby/khash.h"
 KHASH_DECLARE(mt, mrb_sym, struct RProc*, TRUE)
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_PROC_H */
diff --git a/include/mruby/range.h b/include/mruby/range.h
index e30c71ab5..008698fac 100644
--- a/include/mruby/range.h
+++ b/include/mruby/range.h
@@ -10,10 +10,7 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/range.h
- * @defgroup mruby_range Range class
- * @ingroup mruby
- * @{
+ * Range class
  */
 MRB_BEGIN_DECL
 
@@ -31,11 +28,21 @@ struct RRange {
 #define mrb_range_ptr(v)    ((struct RRange*)(mrb_ptr(v)))
 #define mrb_range_value(p)  mrb_obj_value((void*)(p))
 
-MRB_API mrb_value mrb_range_new(mrb_state*, mrb_value, mrb_value, mrb_bool);
+/*
+ * Initializes a Range.
+ *
+ * If the third parameter is FALSE then it includes the last value in the range.
+ * If the third parameter is TRUE then it excludes the last value in the range.
+ *
+ * @param start the beginning value.
+ * @param end the ending value.
+ * @param exclude represents the inclusion or exclusion of the last value.
+ */
+MRB_API mrb_value mrb_range_new(mrb_state *mrb, mrb_value start, mrb_value end, mrb_bool exclude);
+
 MRB_API mrb_bool mrb_range_beg_len(mrb_state *mrb, mrb_value range, mrb_int *begp, mrb_int *lenp, mrb_int len);
 mrb_value mrb_get_values_at(mrb_state *mrb, mrb_value obj, mrb_int olen, mrb_int argc, const mrb_value *argv, mrb_value (*func)(mrb_state*, mrb_value, mrb_int));
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_RANGE_H */
diff --git a/include/mruby/string.h b/include/mruby/string.h
index e182bb6fa..c049a72c7 100644
--- a/include/mruby/string.h
+++ b/include/mruby/string.h
@@ -10,10 +10,7 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/string.h
- * @defgroup mrb_string String class
- * @ingroup mruby
- * @{
+ * String class
  */
 MRB_BEGIN_DECL
 
@@ -69,6 +66,9 @@ struct RString {
 #define RSTR_SET_FROZEN_FLAG(s) ((s)->flags |= MRB_STR_FROZEN)
 #define RSTR_UNSET_FROZEN_FLAG(s) ((s)->flags &= ~MRB_STR_FROZEN)
 
+/*
+ * Returns a pointer from a Ruby string
+ */
 #define mrb_str_ptr(s)       ((struct RString*)(mrb_ptr(s)))
 #define RSTRING(s)           mrb_str_ptr(s)
 #define RSTRING_PTR(s)       RSTR_PTR(RSTRING(s))
@@ -88,34 +88,104 @@ mrb_int mrb_str_strlen(mrb_state*, struct RString*);
 void mrb_gc_free_str(mrb_state*, struct RString*);
 MRB_API void mrb_str_modify(mrb_state*, struct RString*);
 MRB_API void mrb_str_concat(mrb_state*, mrb_value, mrb_value);
+
+/*
+ * Adds two strings together.
+ */
 MRB_API mrb_value mrb_str_plus(mrb_state*, mrb_value, mrb_value);
+
+/*
+ * Converts pointer into a Ruby string.
+ */
 MRB_API mrb_value mrb_ptr_to_str(mrb_state *, void*);
+
+/*
+ * Returns an object as a Ruby string.
+ */
 MRB_API mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj);
+
+/*
+ * Resizes the string's length.
+ */
 MRB_API mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len);
+
+/*
+ * Returns a sub string.
+ */
 MRB_API mrb_value mrb_str_substr(mrb_state *mrb, mrb_value str, mrb_int beg, mrb_int len);
+
+/*
+ * Returns a Ruby string type.
+ */
 MRB_API mrb_value mrb_string_type(mrb_state *mrb, mrb_value str);
+
 MRB_API mrb_value mrb_check_string_type(mrb_state *mrb, mrb_value str);
 MRB_API mrb_value mrb_str_buf_new(mrb_state *mrb, size_t capa);
 
 MRB_API const char *mrb_string_value_cstr(mrb_state *mrb, mrb_value *ptr);
 MRB_API const char *mrb_string_value_ptr(mrb_state *mrb, mrb_value ptr);
+
+/*
+ * Duplicates a string object.
+ */
 MRB_API mrb_value mrb_str_dup(mrb_state *mrb, mrb_value str);
+
+/*
+ * Returns a symbol from a passed in string.
+ */
 MRB_API mrb_value mrb_str_intern(mrb_state *mrb, mrb_value self);
+
 MRB_API mrb_value mrb_str_to_inum(mrb_state *mrb, mrb_value str, mrb_int base, mrb_bool badcheck);
 MRB_API double mrb_str_to_dbl(mrb_state *mrb, mrb_value str, mrb_bool badcheck);
+
+/*
+ * Returns a converted string type.
+ */
 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.
+ */
 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.
+ *
+ * @see mrb_str_cat_cstr
+ */
 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.
+ *
+ * @see mrb_str_cat
+ */
 MRB_API mrb_value mrb_str_cat_cstr(mrb_state *mrb, mrb_value str, const char *ptr);
 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 C string from a Ruby string.
+ */
 MRB_API char *mrb_str_to_cstr(mrb_state *mrb, mrb_value str);
+
 mrb_value mrb_str_pool(mrb_state *mrb, mrb_value str);
 mrb_int 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);
 
 void mrb_noregexp(mrb_state *mrb, mrb_value self);
@@ -126,7 +196,6 @@ void mrb_regexp_check(mrb_state *mrb, mrb_value obj);
 #define mrb_str_buf_cat(mrb, str, ptr, len) mrb_str_cat(mrb, str, ptr, len)
 #define mrb_str_buf_append(mrb, str, str2) mrb_str_cat_str(mrb, str, str2)
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_STRING_H */
diff --git a/include/mruby/value.h b/include/mruby/value.h
index d9614f356..dfad3ec73 100644
--- a/include/mruby/value.h
+++ b/include/mruby/value.h
@@ -10,13 +10,7 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/value.h
- * @defgroup mruby_value Value definitions
- *
- * @ref mrb_value functions and macros.
- *
- * @ingroup mruby
- * @{
+ * MRuby Value definition functions and macros.
  */
 MRB_BEGIN_DECL
 
@@ -134,8 +128,10 @@ enum mrb_vtype {
 #define mrb_test(o)   mrb_bool(o)
 MRB_API mrb_bool mrb_regexp_p(struct mrb_state*, mrb_value);
 
-static inline mrb_value
-mrb_float_value(struct mrb_state *mrb, mrb_float f)
+/*
+ * Returns a float in Ruby.
+ */
+MRB_INLINE mrb_value mrb_float_value(struct mrb_state *mrb, mrb_float f)
 {
   mrb_value v;
   (void) mrb;
@@ -152,8 +148,10 @@ mrb_cptr_value(struct mrb_state *mrb, void *p)
   return v;
 }
 
-static inline mrb_value
-mrb_fixnum_value(mrb_int i)
+/*
+ * Returns a fixnum in Ruby.
+ */
+MRB_INLINE mrb_value mrb_fixnum_value(mrb_int i)
 {
   mrb_value v;
   SET_INT_VALUE(v, i);
@@ -177,7 +175,7 @@ mrb_obj_value(void *p)
 }
 
 
-/**
+/*
  * Get a nil mrb_value object.
  *
  * @return
@@ -190,16 +188,20 @@ MRB_INLINE mrb_value mrb_nil_value(void)
   return v;
 }
 
-static inline mrb_value
-mrb_false_value(void)
+/*
+ * Returns false in Ruby.
+ */
+MRB_INLINE mrb_value mrb_false_value(void)
 {
   mrb_value v;
   SET_FALSE_VALUE(v);
   return v;
 }
 
-static inline mrb_value
-mrb_true_value(void)
+/*
+ * Returns true in Ruby.
+ */
+MRB_INLINE mrb_value mrb_true_value(void)
 {
   mrb_value v;
   SET_TRUE_VALUE(v);
@@ -245,7 +247,6 @@ mrb_ro_data_p(const char *p)
 # define mrb_ro_data_p(p) FALSE
 #endif
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_VALUE_H */
diff --git a/include/mruby/variable.h b/include/mruby/variable.h
index 91d50c106..063d65b71 100644
--- a/include/mruby/variable.h
+++ b/include/mruby/variable.h
@@ -10,10 +10,7 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/variable.h
- * @defgroup mruby_variable Functions to access to mruby variables.
- * @ingroup mruby
- * @{
+ * Functions to access mruby variables.
  */
 MRB_BEGIN_DECL
 
@@ -80,7 +77,6 @@ void mrb_gc_mark_iv(mrb_state*, struct RObject*);
 size_t mrb_gc_mark_iv_size(mrb_state*, struct RObject*);
 void mrb_gc_free_iv(mrb_state*, struct RObject*);
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_VARIABLE_H */
diff --git a/include/mruby/version.h b/include/mruby/version.h
index 09be56811..733863511 100644
--- a/include/mruby/version.h
+++ b/include/mruby/version.h
@@ -10,47 +10,101 @@
 #include "mruby/common.h"
 
 /**
- * @file mruby/version.h
- * @brief MRuby version macros
- * @defgroup mrb_string MRuby version macros
- * @ingroup MRuby
- * @{
+ * mruby version definition macros
  */
 MRB_BEGIN_DECL
 
+/*
+ * A passed in expression.
+ */
 #define MRB_STRINGIZE0(expr) #expr
+
+/*
+ * Passes in an expression to MRB_STRINGIZE0.
+ */
 #define MRB_STRINGIZE(expr) MRB_STRINGIZE0(expr)
 
+/*
+ * The version of Ruby used by mruby.
+ */
 #define MRUBY_RUBY_VERSION "1.9"
+
+/*
+ * Ruby engine.
+ */
 #define MRUBY_RUBY_ENGINE  "mruby"
 
+/*
+ * Major release version number.
+ */
 #define MRUBY_RELEASE_MAJOR 1
+
+/*
+ * Minor release version number.
+ */
 #define MRUBY_RELEASE_MINOR 1
+
+/*
+ * Tiny release version number.
+ */
 #define MRUBY_RELEASE_TEENY 1
 
+/*
+ * The mruby version.
+ */
 #define MRUBY_VERSION MRB_STRINGIZE(MRUBY_RELEASE_MAJOR) "." MRB_STRINGIZE(MRUBY_RELEASE_MINOR) "." MRB_STRINGIZE(MRUBY_RELEASE_TEENY)
+
+/*
+ * Release number.
+ */
 #define MRUBY_RELEASE_NO (MRUBY_RELEASE_MAJOR * 100 * 100 + MRUBY_RELEASE_MINOR * 100 + MRUBY_RELEASE_TEENY)
+
+/*
+ * Release year.
+ */
 #define MRUBY_RELEASE_YEAR 2014
+
+/*
+ * Release month.
+ */
 #define MRUBY_RELEASE_MONTH 11
+
+/*
+ * Release day.
+ */
 #define MRUBY_RELEASE_DAY 19
+
+/*
+ * Release date as a string.
+ */
 #define MRUBY_RELEASE_DATE MRB_STRINGIZE(MRUBY_RELEASE_YEAR) "-" MRB_STRINGIZE(MRUBY_RELEASE_MONTH) "-" MRB_STRINGIZE(MRUBY_RELEASE_DAY)
 
+/*
+ * The year mruby was first created.
+ */
 #define MRUBY_BIRTH_YEAR 2010
 
+/*
+ * MRuby's authors.
+ */
 #define MRUBY_AUTHOR "mruby developers"
 
-
+/*
+ * mruby's version, and release date.
+ */
 #define MRUBY_DESCRIPTION      \
   "mruby " MRUBY_VERSION       \
   " (" MRUBY_RELEASE_DATE ") " \
 
+/*
+ * mruby's copyright information.
+ */
 #define MRUBY_COPYRIGHT                \
   "mruby - Copyright (c) "             \
   MRB_STRINGIZE(MRUBY_BIRTH_YEAR)"-"   \
   MRB_STRINGIZE(MRUBY_RELEASE_YEAR)" " \
   MRUBY_AUTHOR                         \
 
-/** @} */
 MRB_END_DECL
 
 #endif  /* MRUBY_VERSION_H */