Sorting documentation grouping

18 files changed, 131 insertions, 94 deletions

diff --git a/include/mruby.h b/include/mruby.h
index 77dfe03df..6d8b5555d 100644
--- a/include/mruby.h
+++ b/include/mruby.h
@@ -40,15 +40,19 @@
 /**
  * @file mruby.h
  * @brief Main header of mruby C API. Include this first.
- * @defgroup mrb_core MRuby core
- * @ingroup MRuby
+ * @defgroup mruby MRuby C API
  * @{
  */
 MRB_BEGIN_DECL
 
 typedef uint32_t mrb_code;
+
+/**
+ * Required arguments signature type.
+ */
 typedef uint32_t mrb_aspec;
 
+
 struct mrb_irep;
 struct mrb_state;
 
@@ -245,19 +249,17 @@ MRB_API void mrb_prepend_module(mrb_state*, struct RClass*, struct RClass*);
  *
  * If you're creating a gem it may look something like this:
  *
- *     mrb_value example_method(mrb_state* mrb, mrb_value self){
+ *     mrb_value example_method(mrb_state* mrb, mrb_value self)
+ *     {
  *          puts("Executing example command!");
  *          return self;
  *     }
  *
- *     void mrb_example_gem_init(mrb_state* mrb) {
+ *     void mrb_example_gem_init(mrb_state* mrb)
+ *     {
  *           mrb_define_method(mrb, mrb->kernel_module, "example_method", example_method, MRB_ARGS_NONE());
  *     }
  *
- *     void mrb_example_gem_final(mrb_state* mrb) {
- *         //free(TheAnimals);
- *     }
- *
  * @param mrb
  *      The MRuby state reference.
  * @param cla
@@ -265,7 +267,8 @@ MRB_API void mrb_prepend_module(mrb_state*, struct RClass*, struct RClass*);
  * @param func
  *      The function pointer to the method definition.
  * @param aspec
- *      The method required parameters definition.
+ *      The method parameters declaration.
+ *      See @ref mruby_mrb_aspec for details.
  */
 MRB_API void mrb_define_method(mrb_state *mrb, struct RClass *cla, const char *name, mrb_func_t func, mrb_aspec aspec);
 
@@ -293,28 +296,95 @@ MRB_API mrb_bool mrb_obj_respond_to(mrb_state *mrb, struct RClass* c, mrb_sym mi
 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);
 
-/* required arguments */
+/**
+ * @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
+ *
+ * @{
+ */
+
+/**
+ * Function requires n arguments.
+ *
+ * @param n
+ *      The number of required arguments.
+ */
 #define MRB_ARGS_REQ(n)     ((mrb_aspec)((n)&0x1f) << 18)
-/* optional arguments */
+
+/**
+ * Funtion takes n optional arguments
+ *
+ * @param n
+ *      The number of optional arguments.
+ */
 #define MRB_ARGS_OPT(n)     ((mrb_aspec)((n)&0x1f) << 13)
-/* mandatory and optinal arguments */
+
+/**
+ * Funtion takes n1 mandatory arguments and n2 optional arguments
+ *
+ * @param n1
+ *      The number of required arguments.
+ * @param n2
+ *      The number of optional arguments.
+ */
 #define MRB_ARGS_ARG(n1,n2)   (MRB_ARGS_REQ(n1)|MRB_ARGS_OPT(n2))
 
-/* rest argument */
+/** rest argument */
 #define MRB_ARGS_REST()     ((mrb_aspec)(1 << 12))
-/* required arguments after rest */
+
+/** required arguments after rest */
 #define MRB_ARGS_POST(n)    ((mrb_aspec)((n)&0x1f) << 7)
-/* keyword arguments (n of keys, kdict) */
+
+/** keyword arguments (n of keys, kdict) */
 #define MRB_ARGS_KEY(n1,n2) ((mrb_aspec)((((n1)&0x1f) << 2) | ((n2)?(1<<1):0)))
-/* block argument */
+
+/**
+ * Function takes a block argument
+ */
 #define MRB_ARGS_BLOCK()    ((mrb_aspec)1)
 
-/* accept any number of arguments */
+/**
+ * Function accepts any number of arguments
+ */
 #define MRB_ARGS_ANY()      MRB_ARGS_REST()
-/* accept no arguments */
+
+/**
+ * Function accepts no arguments
+ */
 #define MRB_ARGS_NONE()     ((mrb_aspec)0)
 
-/** Retrieve arguments from mrb_state.
+/** @} */
+
+/**
+ * Format specifiers for \ref mrb_get_args function
+ *
+ * Must be a list of following format specifiers:
+ *
+ * | char | mruby type     | retrieve types      |note                                                |
+ * |:----:|----------------|---------------------|----------------------------------------------------|
+ * | o    | Object         | mrb_value           | Could be used to retrieve any type of argument     |
+ * | C    | Class/Module   | mrb_value           |                                                    |
+ * | S    | String         | mrb_value           | when ! follows, the value may be nil               |
+ * | A    | Array          | mrb_value           | when ! follows, the value may be nil               |
+ * | H    | Hash           | mrb_value           | when ! follows, the value may be nil               |
+ * | s    | String         | char *, mrb_int      |  Receive two arguments; s! gives (NULL,0) for nil  |
+ * | z    | String         | char *               | NUL terminated string; z! gives NULL for nil       |
+ * | a    | Array          | mrb_value *, mrb_int | Receive two arguments; a! gives (NULL,0) for nil   |
+ * | f    | Float          | mrb_float           |                                                    |
+ * | i    | Integer        | mrb_int             |                                                    |
+ * | b    | boolean        | mrb_bool            |                                                    |
+ * | n    | Symbol         | mrb_sym             |                                                    |
+ * | &    | block          | mrb_value           |                                                    |
+ * | *    | rest arguments | mrb_value *, mrb_int | Receive the rest of arguments as an array.         |
+ * | \|   | optional       |                     | After this spec following specs would be optional. |
+ * | ?    | optional given | mrb_bool            | True if preceding argument is given. Used to check optional argument is given. |
+ */
+typedef const char *mrb_args_format;
+
+/**
+ * Retrieve arguments from mrb_state.
  *
  * When applicable, implicit conversions (such as to_str, to_ary, to_hash) are
  * applied to received arguments.
@@ -322,36 +392,14 @@ MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *o
  *
  * @param mrb
  *      The current MRuby state.
- *
  * @param format
- *      is a list of following format specifiers:
- *      <pre>
- *        char mruby type      retrieve types       note
- *        o    Object          mrb_value            Could be used to retrieve any type of argument
- *        C    Class/Module    mrb_value
- *        S    String          mrb_value            when ! follows, the value may be nil
- *        A    Array           mrb_value            when ! follows, the value may be nil
- *        H    Hash            mrb_value            when ! follows, the value may be nil
- *        s    String          char*, mrb_int       Receive two arguments; s! gives (NULL,0) for nil
- *        z    String          char*                NUL terminated string; z! gives NULL for nil
- *        a    Array           mrb_value*, mrb_int  Receive two arguments; a! gives (NULL,0) for nil
- *        f    Float           mrb_float
- *        i    Integer         mrb_int
- *        b    boolean         mrb_bool
- *        n    Symbol          mrb_sym
- *        &    block           mrb_value
- *        *    rest arguments  mrb_value*, mrb_int  Receive the rest of arguments as an array.
- *        |    optional                             After this spec following specs would be optional.
- *        ?    optional given  mrb_bool             True if preceding argument is given. Used to check optional argument is given.
- *      </pre>
- *
+ *      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, const char *format, ...);
+MRB_API mrb_int mrb_get_args(mrb_state *mrb, mrb_args_format format, ...);
 
 /* `strlen` for character string literals (use with caution or `strlen` instead)
     Adjacent string literals are concatenated in C/C++ in translation phase 6.
diff --git a/include/mruby/array.h b/include/mruby/array.h
index 1befdb756..ca92486d6 100644
--- a/include/mruby/array.h
+++ b/include/mruby/array.h
@@ -11,9 +11,8 @@
 
 /**
  * @file mruby/array.h
- * @brief Array class
- * @defgroup mrb_array MRuby Array class
- * @ingroup MRuby
+ * @defgroup mruby_array Array class
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/class.h b/include/mruby/class.h
index 2f23f5d67..35edce86c 100644
--- a/include/mruby/class.h
+++ b/include/mruby/class.h
@@ -11,9 +11,8 @@
 
 /**
  * @file mruby/class.h
- * @brief Class class
- * @defgroup mrb_class MRuby Class class
- * @ingroup MRuby
+ * @defgroup mruby_class Class class
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/compile.h b/include/mruby/compile.h
index bfa2d80ef..c482ddf69 100644
--- a/include/mruby/compile.h
+++ b/include/mruby/compile.h
@@ -11,9 +11,8 @@
 
 /**
  * @file mruby/compile.h
- * @brief MRuby compiler
- * @defgroup mrb_compile MRuby compiler
- * @ingroup MRuby
+ * @defgroup mruby_compile Compiler
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/data.h b/include/mruby/data.h
index ddb4c699b..8fd798455 100644
--- a/include/mruby/data.h
+++ b/include/mruby/data.h
@@ -11,9 +11,8 @@
 
 /**
  * @file mruby/data.h
- * @brief User defined objects.
- * @defgroup mrb_string MRuby User defined objects.
- * @ingroup MRuby
+ * @defgroup mruby_data User defined objects.
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/debug.h b/include/mruby/debug.h
index 1df614c07..94ef1e723 100644
--- a/include/mruby/debug.h
+++ b/include/mruby/debug.h
@@ -11,9 +11,8 @@
 
 /**
  * @file mruby/debug.h
- * @brief Debugging.
- * @defgroup mrb_string MRuby Debugging.
- * @ingroup MRuby
+ * @defgroup mruby_debug Debugging.
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/dump.h b/include/mruby/dump.h
index bf113c6ea..293122f9a 100644
--- a/include/mruby/dump.h
+++ b/include/mruby/dump.h
@@ -13,9 +13,8 @@
 
 /**
  * @file mruby/dump.h
- * @brief Dumping compiled mruby script.
- * @defgroup mrb_dump Dumping compiled mruby script.
- * @ingroup MRuby
+ * @defgroup mruby_dump Dumping compiled mruby script.
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/error.h b/include/mruby/error.h
index e9d3465c3..347ca7738 100644
--- a/include/mruby/error.h
+++ b/include/mruby/error.h
@@ -11,9 +11,8 @@
 
 /**
  * @file mruby/error.h
- * @brief Error handling.
- * @defgroup mrb_error MRuby Error handling.
- * @ingroup MRuby
+ * @defgroup mruby_error Error handling.
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/gc.h b/include/mruby/gc.h
index a19378e82..a9187bb56 100644
--- a/include/mruby/gc.h
+++ b/include/mruby/gc.h
@@ -11,9 +11,8 @@
 
 /**
  * @file mruby/gc.h
- * @brief Uncommon memory management stuffs.
- * @defgroup mrb_gc MRuby garbage collection.
- * @ingroup MRuby
+ * @defgroup mruby_gc Uncommon memory management stuffs.
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/hash.h b/include/mruby/hash.h
index c52c2ec19..1f69b4215 100644
--- a/include/mruby/hash.h
+++ b/include/mruby/hash.h
@@ -11,9 +11,8 @@
 
 /**
  * @file mruby/hash.h
- * @brief Hash class
- * @defgroup mrb_hash MRuby Hash class
- * @ingroup MRuby
+ * @defgroup mruby_hash Hash class
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/irep.h b/include/mruby/irep.h
index 833a8adf5..1f08f44fa 100644
--- a/include/mruby/irep.h
+++ b/include/mruby/irep.h
@@ -12,9 +12,8 @@
 
 /**
  * @file mruby/irep.h
- * @brief Compiled mruby script.
- * @defgroup mrb_irep Compiled mruby script.
- * @ingroup MRuby
+ * @defgroup mruby_irep Compiled mruby scripts.
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/khash.h b/include/mruby/khash.h
index 3458a2b8e..36119bfcf 100644
--- a/include/mruby/khash.h
+++ b/include/mruby/khash.h
@@ -14,9 +14,8 @@
 
 /**
  * @file mruby/khash.h
- * @brief Defines of khash which is used in hash table of mruby.
- * @defgroup mrb_khash Defines of khash which is used in hash table of mruby.
- * @ingroup MRuby
+ * @defgroup mruby_khash khash definitions used in mruby's hash table.
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/numeric.h b/include/mruby/numeric.h
index 6dcc30a55..a7aa6c81b 100644
--- a/include/mruby/numeric.h
+++ b/include/mruby/numeric.h
@@ -11,9 +11,11 @@
 
 /**
  * @file mruby/numeric.h
- * @brief Numeric class and sub-classes of it.
- * @defgroup mrb_string Numeric class and sub-classes of it.
- * @ingroup MRuby
+ * @defgroup mruby_numeric Numeric class and it's sub-classes.
+ *
+ * Numeric, Integer, Float, Fixnum classes
+ *
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/proc.h b/include/mruby/proc.h
index 064d518b3..6b8d3cd9f 100644
--- a/include/mruby/proc.h
+++ b/include/mruby/proc.h
@@ -12,9 +12,8 @@
 
 /**
  * @file mruby/proc.h
- * @brief Proc class
- * @defgroup mrb_proc MRuby Proc class
- * @ingroup MRuby
+ * @defgroup mruby_proc Proc class
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/range.h b/include/mruby/range.h
index 4b55557e8..e30c71ab5 100644
--- a/include/mruby/range.h
+++ b/include/mruby/range.h
@@ -11,9 +11,8 @@
 
 /**
  * @file mruby/range.h
- * @brief Range class
- * @defgroup mrb_range MRuby Range class
- * @ingroup MRuby
+ * @defgroup mruby_range Range class
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/string.h b/include/mruby/string.h
index a8239b221..e182bb6fa 100644
--- a/include/mruby/string.h
+++ b/include/mruby/string.h
@@ -11,9 +11,8 @@
 
 /**
  * @file mruby/string.h
- * @brief String class
- * @defgroup mrb_string MRuby String class
- * @ingroup MRuby
+ * @defgroup mrb_string String class
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/value.h b/include/mruby/value.h
index 0fb6703b1..e257c6b8c 100644
--- a/include/mruby/value.h
+++ b/include/mruby/value.h
@@ -11,9 +11,11 @@
 
 /**
  * @file mruby/value.h
- * @brief mrb_value functions and macros.
- * @defgroup mrb_value mrb_value functions and macros.
- * @ingroup MRuby
+ * @defgroup mruby_value Value definitions
+ *
+ * @ref mrb_value functions and macros.
+ *
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
diff --git a/include/mruby/variable.h b/include/mruby/variable.h
index 9aaece1d3..91d50c106 100644
--- a/include/mruby/variable.h
+++ b/include/mruby/variable.h
@@ -11,9 +11,8 @@
 
 /**
  * @file mruby/variable.h
- * @brief Functions to access mruby variables.
- * @defgroup mrb_variable Functions to access to mruby variables.
- * @ingroup MRuby
+ * @defgroup mruby_variable Functions to access to mruby variables.
+ * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL