From 7505bad67769e9c70e000c4b3a72b37f014555db Mon Sep 17 00:00:00 2001
From: Seba Gamboa <me@sagmor.com>
Date: Fri, 18 Sep 2015 23:59:29 -0300
Subject: Playing around with some documentations schemes

---
 include/mruby.h        | 59 +++++++++++++++++++++++++++++---------------------
 include/mruby/string.h | 13 ++++++-----
 2 files changed, 41 insertions(+), 31 deletions(-)

(limited to 'include')

diff --git a/include/mruby.h b/include/mruby.h
index dedbd0748..f4accb9d2 100644
--- a/include/mruby.h
+++ b/include/mruby.h
@@ -1,28 +1,30 @@
 /*
-** mruby - An embeddable Ruby implementation
-**
-** Copyright (c) mruby developers 2010-2015
-**
-** Permission is hereby granted, free of charge, to any person obtaining
-** a copy of this software and associated documentation files (the
-** "Software"), to deal in the Software without restriction, including
-** without limitation the rights to use, copy, modify, merge, publish,
-** distribute, sublicense, and/or sell copies of the Software, and to
-** permit persons to whom the Software is furnished to do so, subject to
-** the following conditions:
-**
-** The above copyright notice and this permission notice shall be
-** included in all copies or substantial portions of the Software.
-**
-** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-** EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-** MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-** IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-** CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-** TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-** SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-**
-** [ MIT license: http://www.opensource.org/licenses/mit-license.php ]
+ * mruby - An embeddable Ruby implementation
+ *
+ * Copyright (c) mruby developers 2010-2015
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+ * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+ * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * [ MIT license: http://www.opensource.org/licenses/mit-license.php ]
+ *
+ * @header mruby.h
 */
 
 #ifndef MRUBY_H
@@ -202,7 +204,14 @@ typedef struct mrb_state {
 #endif
 
 typedef mrb_value (*mrb_func_t)(mrb_state *mrb, mrb_value);
-MRB_API struct RClass *mrb_define_class(mrb_state *, const char*, struct RClass*);
+
+/**
+ * Define a new Class
+ *
+ * @param name The name of the defined class
+ * @param super The new class parent
+ */
+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*);
diff --git a/include/mruby/string.h b/include/mruby/string.h
index c4b31216e..3c428ac54 100644
--- a/include/mruby/string.h
+++ b/include/mruby/string.h
@@ -1,8 +1,9 @@
-/*
-** mruby/string.h - String class
-**
-** See Copyright Notice in mruby.h
-*/
+/**
+ * @header mruby/string.h
+ * @copyright See Copyright Notice in mruby.h
+ *
+ * String class
+ */
 
 #ifndef MRUBY_STRING_H
 #define MRUBY_STRING_H
@@ -67,7 +68,7 @@ struct RString {
 #define RSTRING(s)           mrb_str_ptr(s)
 #define RSTRING_PTR(s)       RSTR_PTR(RSTRING(s))
 #define RSTRING_EMBED_LEN(s) RSTR_ENBED_LEN(RSTRING(s))
-#define RSTRING_LEN(s)       RSTR_LEN(RSTRING(s))  
+#define RSTRING_LEN(s)       RSTR_LEN(RSTRING(s))
 #define RSTRING_CAPA(s)      RSTR_CAPA(RSTRING(s))
 #define RSTRING_END(s)       (RSTRING_PTR(s) + RSTRING_LEN(s))
 mrb_int mrb_str_strlen(mrb_state*, struct RString*);
-- 
cgit v1.2.3


From f36944f551a1fc899c981939f3ed5bdba7936cf9 Mon Sep 17 00:00:00 2001
From: Seba Gamboa <me@sagmor.com>
Date: Sun, 20 Sep 2015 18:57:17 -0300
Subject: Merging documentation from docs

---
 include/mruby.h | 150 ++++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 123 insertions(+), 27 deletions(-)

(limited to 'include')

diff --git a/include/mruby.h b/include/mruby.h
index f4accb9d2..0e53a4a10 100644
--- a/include/mruby.h
+++ b/include/mruby.h
@@ -1,32 +1,36 @@
 /*
- * mruby - An embeddable Ruby implementation
- *
- * Copyright (c) mruby developers 2010-2015
- *
- * Permission is hereby granted, free of charge, to any person obtaining
- * a copy of this software and associated documentation files (the
- * "Software"), to deal in the Software without restriction, including
- * without limitation the rights to use, copy, modify, merge, publish,
- * distribute, sublicense, and/or sell copies of the Software, and to
- * permit persons to whom the Software is furnished to do so, subject to
- * the following conditions:
- *
- * The above copyright notice and this permission notice shall be
- * included in all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
- * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
- * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
- * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
- * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
- * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
- * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- *
- * [ MIT license: http://www.opensource.org/licenses/mit-license.php ]
- *
- * @header mruby.h
+** mruby - An embeddable Ruby implementation
+**
+** Copyright (c) mruby developers 2010-2015
+**
+** Permission is hereby granted, free of charge, to any person obtaining
+** a copy of this software and associated documentation files (the
+** "Software"), to deal in the Software without restriction, including
+** without limitation the rights to use, copy, modify, merge, publish,
+** distribute, sublicense, and/or sell copies of the Software, and to
+** permit persons to whom the Software is furnished to do so, subject to
+** the following conditions:
+**
+** The above copyright notice and this permission notice shall be
+** included in all copies or substantial portions of the Software.
+**
+** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+** EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+** MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+** IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+** CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+** TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+** SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+**
+** [ MIT license: http://www.opensource.org/licenses/mit-license.php ]
 */
 
+/**
+ * @header mruby.h
+ *
+ * Basic mruby header.
+ */
+
 #ifndef MRUBY_H
 #define MRUBY_H
 
@@ -48,6 +52,13 @@ typedef uint32_t mrb_aspec;
 struct mrb_irep;
 struct mrb_state;
 
+/**
+ * Function pointer type of custom allocator used in 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.
+ */
 typedef void* (*mrb_allocf) (struct mrb_state *mrb, void*, size_t, void *ud);
 
 #ifndef MRB_GC_ARENA_SIZE
@@ -206,7 +217,19 @@ typedef struct mrb_state {
 typedef mrb_value (*mrb_func_t)(mrb_state *mrb, mrb_value);
 
 /**
- * Define a new Class
+ * 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>
  *
  * @param name The name of the defined class
  * @param super The new class parent
@@ -217,6 +240,23 @@ MRB_API mrb_value mrb_singleton_class(mrb_state*, mrb_value);
 MRB_API void mrb_include_module(mrb_state*, struct RClass*, struct RClass*);
 MRB_API void mrb_prepend_module(mrb_state*, struct RClass*, struct RClass*);
 
+/**
+ * Defines a global function in ruby.
+ *
+ * If you're creating a gem it may look something like this:
+ *    mrb_value example_method(mrb_state* mrb, mrb_value self){
+ *        puts("Executing example command!");
+ *        return self;
+ *    }
+ *
+ *    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);
+ *    }
+ */
 MRB_API void mrb_define_method(mrb_state*, struct RClass*, const char*, mrb_func_t, mrb_aspec);
 MRB_API void mrb_define_class_method(mrb_state *, struct RClass *, const char *, mrb_func_t, mrb_aspec);
 MRB_API void mrb_define_singleton_method(mrb_state*, struct RObject*, const char*, mrb_func_t, mrb_aspec);
@@ -263,6 +303,39 @@ MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *o
 /* accept no arguments */
 #define MRB_ARGS_NONE()     ((mrb_aspec)0)
 
+/**
+ * Retrieve arguments from mrb_state.
+ * When applicable, implicit conversions (such as to_str, to_ary, to_hash) are
+ * applied to received arguments.
+ * Use it inside a function pointed by mrb_func_t.
+ * @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>
+ *
+ * @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, ...);
 
 /* `strlen` for character string literals (use with caution or `strlen` instead)
@@ -273,6 +346,9 @@ MRB_API mrb_int mrb_get_args(mrb_state *mrb, const char *format, ...);
 */
 #define mrb_strlen_lit(lit) (sizeof(lit "") - 1)
 
+/**
+ * Call existing ruby functions.
+ */
 MRB_API mrb_value mrb_funcall(mrb_state*, mrb_value, const char*, mrb_int,...);
 MRB_API mrb_value mrb_funcall_argv(mrb_state*, mrb_value, mrb_sym, mrb_int, const mrb_value*);
 MRB_API mrb_value mrb_funcall_with_block(mrb_state*, mrb_value, mrb_sym, mrb_int, const mrb_value*, mrb_value);
@@ -297,6 +373,10 @@ MRB_API struct RBasic *mrb_obj_alloc(mrb_state*, enum mrb_vtype, struct RClass*)
 MRB_API void mrb_free(mrb_state*, void*);
 
 MRB_API mrb_value mrb_str_new(mrb_state *mrb, const char *p, size_t len);
+
+/**
+ * Turns a C string into a Ruby string value.
+ */
 MRB_API mrb_value mrb_str_new_cstr(mrb_state*, const char*);
 MRB_API mrb_value mrb_str_new_static(mrb_state *mrb, const char *p, size_t len);
 #define mrb_str_new_lit(mrb, lit) mrb_str_new_static(mrb, (lit), mrb_strlen_lit(lit))
@@ -313,9 +393,25 @@ char* mrb_locale_from_utf8(const char *p, size_t len);
 #define mrb_utf8_free(p)
 #endif
 
+/**
+ * Creates new mrb_state.
+ */
 MRB_API mrb_state* mrb_open(void);
+
+
+/**
+ * Create new mrb_state with custom allocator.
+ *
+ * @param ud
+ *      will be passed to custom allocator f. If user data isn't required just
+ *      pass NULL. Function pointer f must satisfy requirements of its type.
+ */
 MRB_API mrb_state* mrb_open_allocf(mrb_allocf, void *ud);
 MRB_API mrb_state* mrb_open_core(mrb_allocf, void *ud);
+
+/**
+ * Deletes mrb_state.
+ */
 MRB_API void mrb_close(mrb_state*);
 
 MRB_API void* mrb_default_allocf(mrb_state*, void*, size_t, void*);
-- 
cgit v1.2.3


From c127614638aeb66d5c97a09f7a16ae51dfd9d7e2 Mon Sep 17 00:00:00 2001
From: Seba Gamboa <me@sagmor.com>
Date: Sun, 20 Sep 2015 21:14:07 -0300
Subject: Setting up doxygen groups

---
 include/mrbconf.h        | 11 -------
 include/mruby.h          | 79 +++++++++++++++++++++++++++++++-----------------
 include/mruby/array.h    | 18 +++++++----
 include/mruby/class.h    | 18 +++++++----
 include/mruby/common.h   | 35 +++++++++++++++++++++
 include/mruby/compile.h  | 18 +++++++----
 include/mruby/data.h     | 18 +++++++----
 include/mruby/debug.h    | 18 +++++++----
 include/mruby/dump.h     | 21 ++++++++-----
 include/mruby/error.h    | 18 +++++++----
 include/mruby/gc.h       | 18 +++++++----
 include/mruby/hash.h     | 18 +++++++----
 include/mruby/irep.h     | 19 +++++++-----
 include/mruby/khash.h    | 20 +++++++-----
 include/mruby/numeric.h  | 18 +++++++----
 include/mruby/proc.h     | 17 +++++++----
 include/mruby/range.h    | 18 +++++++----
 include/mruby/string.h   | 29 ++++++++++--------
 include/mruby/value.h    | 14 +++++++++
 include/mruby/variable.h | 18 +++++++----
 include/mruby/version.h  | 14 +++++++++
 21 files changed, 312 insertions(+), 145 deletions(-)
 create mode 100644 include/mruby/common.h

(limited to 'include')

diff --git a/include/mrbconf.h b/include/mrbconf.h
index 95d4b3637..4b95637b8 100644
--- a/include/mrbconf.h
+++ b/include/mrbconf.h
@@ -100,15 +100,4 @@
 # define TRUE 1
 #endif
 
-#if defined(MRB_BUILD_AS_DLL)
-
-#if defined(MRB_CORE) || defined(MRB_LIB)
-#define MRB_API __declspec(dllexport)
-#else
-#define MRB_API __declspec(dllimport)
-#endif
-#else
-#define MRB_API extern
-#endif
-
 #endif  /* MRUBYCONF_H */
diff --git a/include/mruby.h b/include/mruby.h
index 0e53a4a10..77dfe03df 100644
--- a/include/mruby.h
+++ b/include/mruby.h
@@ -25,27 +25,27 @@
 ** [ MIT license: http://www.opensource.org/licenses/mit-license.php ]
 */
 
-/**
- * @header mruby.h
- *
- * Basic mruby header.
- */
-
 #ifndef MRUBY_H
 #define MRUBY_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
-
 #include <stdint.h>
 #include <stddef.h>
 #include <limits.h>
 
 #include "mrbconf.h"
+#include "mruby/common.h"
 #include "mruby/value.h"
 #include "mruby/version.h"
 
+/**
+ * @file mruby.h
+ * @brief Main header of mruby C API. Include this first.
+ * @defgroup mrb_core MRuby core
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
+
 typedef uint32_t mrb_code;
 typedef uint32_t mrb_aspec;
 
@@ -244,20 +244,31 @@ MRB_API void mrb_prepend_module(mrb_state*, struct RClass*, struct RClass*);
  * Defines a global function in ruby.
  *
  * If you're creating a gem it may look something like this:
- *    mrb_value example_method(mrb_state* mrb, mrb_value self){
- *        puts("Executing example command!");
- *        return self;
- *    }
  *
- *    void mrb_example_gem_init(mrb_state* mrb) {
- *      mrb_define_method(mrb, mrb->kernel_module, "example_method", example_method, MRB_ARGS_NONE());  
- *    }
+ *     mrb_value example_method(mrb_state* mrb, mrb_value self){
+ *          puts("Executing example command!");
+ *          return self;
+ *     }
  *
- *    void mrb_example_gem_final(mrb_state* mrb) {
- *      //free(TheAnimals);
- *    }
+ *     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
+ *      The class pointer where the method will be defined.
+ * @param func
+ *      The function pointer to the method definition.
+ * @param aspec
+ *      The method required parameters definition.
  */
-MRB_API void mrb_define_method(mrb_state*, struct RClass*, const char*, mrb_func_t, mrb_aspec);
+MRB_API void mrb_define_method(mrb_state *mrb, struct RClass *cla, const char *name, mrb_func_t func, mrb_aspec aspec);
+
 MRB_API void mrb_define_class_method(mrb_state *, struct RClass *, const char *, mrb_func_t, mrb_aspec);
 MRB_API void mrb_define_singleton_method(mrb_state*, struct RObject*, const char*, mrb_func_t, mrb_aspec);
 MRB_API void mrb_define_module_function(mrb_state*, struct RClass*, const char*, mrb_func_t, mrb_aspec);
@@ -303,11 +314,15 @@ MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *o
 /* accept no arguments */
 #define MRB_ARGS_NONE()     ((mrb_aspec)0)
 
-/**
- * Retrieve arguments from mrb_state.
+/** Retrieve arguments from mrb_state.
+ *
  * When applicable, implicit conversions (such as to_str, to_ary, to_hash) are
  * 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 following format specifiers:
  *      <pre>
@@ -395,6 +410,9 @@ char* mrb_locale_from_utf8(const char *p, size_t len);
 
 /**
  * Creates new mrb_state.
+ *
+ * @returns
+ *      Pointer to the newly created mrb_state.
  */
 MRB_API mrb_state* mrb_open(void);
 
@@ -405,14 +423,20 @@ MRB_API mrb_state* mrb_open(void);
  * @param ud
  *      will be passed to custom allocator f. If user data isn't required just
  *      pass NULL. Function pointer f must satisfy requirements of its type.
+ *
+ * @returns
+ *      Pointer to the newly created mrb_state.
  */
 MRB_API mrb_state* mrb_open_allocf(mrb_allocf, void *ud);
 MRB_API mrb_state* mrb_open_core(mrb_allocf, void *ud);
 
 /**
- * Deletes mrb_state.
+ * Closes and frees a mrb_state.
+ *
+ * @param mrb
+ *      Pointer to the mrb_state to be closed.
  */
-MRB_API void mrb_close(mrb_state*);
+MRB_API void mrb_close(mrb_state *mrb);
 
 MRB_API void* mrb_default_allocf(mrb_state*, void*, size_t, void*);
 
@@ -570,8 +594,7 @@ MRB_API void mrb_show_copyright(mrb_state *mrb);
 
 MRB_API mrb_value mrb_format(mrb_state *mrb, const char *format, ...);
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_H */
diff --git a/include/mruby/array.h b/include/mruby/array.h
index 0b17b47fd..1befdb756 100644
--- a/include/mruby/array.h
+++ b/include/mruby/array.h
@@ -7,9 +7,16 @@
 #ifndef MRUBY_ARRAY_H
 #define MRUBY_ARRAY_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+#include "mruby/common.h"
+
+/**
+ * @file mruby/array.h
+ * @brief Array class
+ * @defgroup mrb_array MRuby Array class
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 typedef struct mrb_shared_array {
   int refcnt;
@@ -67,8 +74,7 @@ mrb_ary_len(mrb_state *mrb, mrb_value ary)
   return RARRAY_LEN(ary);
 }
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_ARRAY_H */
diff --git a/include/mruby/class.h b/include/mruby/class.h
index 85f3e12c6..2f23f5d67 100644
--- a/include/mruby/class.h
+++ b/include/mruby/class.h
@@ -7,9 +7,16 @@
 #ifndef MRUBY_CLASS_H
 #define MRUBY_CLASS_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+#include "mruby/common.h"
+
+/**
+ * @file mruby/class.h
+ * @brief Class class
+ * @defgroup mrb_class MRuby Class class
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 struct RClass {
   MRB_OBJECT_HEADER;
@@ -81,8 +88,7 @@ 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*);
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_CLASS_H */
diff --git a/include/mruby/common.h b/include/mruby/common.h
new file mode 100644
index 000000000..0a7cd2f1e
--- /dev/null
+++ b/include/mruby/common.h
@@ -0,0 +1,35 @@
+/*
+** mruby/common.h - mruby common platform definitions
+**
+** See Copyright Notice in mruby.h
+*/
+
+#ifndef MRUBY_COMMON_H
+#define MRUBY_COMMON_H
+
+#ifdef __cplusplus
+/** Start declarations in C++ mode */
+#define MRB_BEGIN_DECL extern "C" {
+/** End declarations in C++ mode */
+#define MRB_END_DECL	}
+#else
+/** Start declarations in C mode */
+#define MRB_BEGIN_DECL /* empty */
+/** End declarations in C mode */
+#define MRB_END_DECL	/* empty */
+#endif
+
+
+#if defined(MRB_BUILD_AS_DLL)
+#if defined(MRB_CORE) || defined(MRB_LIB)
+#define MRB_API __declspec(dllexport)
+#else
+#define MRB_API __declspec(dllimport)
+#endif
+#else
+#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 1fb81782d..bfa2d80ef 100644
--- a/include/mruby/compile.h
+++ b/include/mruby/compile.h
@@ -7,9 +7,16 @@
 #ifndef MRUBY_COMPILE_H
 #define MRUBY_COMPILE_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+#include "mruby/common.h"
+
+/**
+ * @file mruby/compile.h
+ * @brief MRuby compiler
+ * @defgroup mrb_compile MRuby compiler
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 #include "mruby.h"
 
@@ -183,8 +190,7 @@ MRB_API mrb_value mrb_load_file_cxt(mrb_state*,FILE*, mrbc_context *cxt);
 MRB_API mrb_value mrb_load_string_cxt(mrb_state *mrb, const char *s, mrbc_context *cxt);
 MRB_API mrb_value mrb_load_nstring_cxt(mrb_state *mrb, const char *s, int len, mrbc_context *cxt);
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif /* MRUBY_COMPILE_H */
diff --git a/include/mruby/data.h b/include/mruby/data.h
index d457e3722..ddb4c699b 100644
--- a/include/mruby/data.h
+++ b/include/mruby/data.h
@@ -7,9 +7,16 @@
 #ifndef MRUBY_DATA_H
 #define MRUBY_DATA_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+#include "mruby/common.h"
+
+/**
+ * @file mruby/data.h
+ * @brief User defined objects.
+ * @defgroup mrb_string MRuby User defined objects.
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 typedef struct mrb_data_type {
   const char *struct_name;
@@ -59,8 +66,7 @@ mrb_data_init(mrb_value v, void *ptr, const mrb_data_type *type)
   DATA_TYPE(v) = type;
 }
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif /* MRUBY_DATA_H */
diff --git a/include/mruby/debug.h b/include/mruby/debug.h
index 0860ba8d5..1df614c07 100644
--- a/include/mruby/debug.h
+++ b/include/mruby/debug.h
@@ -7,9 +7,16 @@
 #ifndef MRUBY_DEBUG_H
 #define MRUBY_DEBUG_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+#include "mruby/common.h"
+
+/**
+ * @file mruby/debug.h
+ * @brief Debugging.
+ * @defgroup mrb_string MRuby Debugging.
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 typedef enum mrb_debug_line_type {
   mrb_debug_line_ary = 0,
@@ -58,8 +65,7 @@ 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);
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif /* MRUBY_DEBUG_H */
diff --git a/include/mruby/dump.h b/include/mruby/dump.h
index 4cee3c0ac..bf113c6ea 100644
--- a/include/mruby/dump.h
+++ b/include/mruby/dump.h
@@ -7,12 +7,18 @@
 #ifndef MRUBY_DUMP_H
 #define MRUBY_DUMP_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
-
 #include "mruby.h"
 #include "mruby/irep.h"
+#include "mruby/common.h"
+
+/**
+ * @file mruby/dump.h
+ * @brief Dumping compiled mruby script.
+ * @defgroup mrb_dump Dumping compiled mruby script.
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 #define DUMP_DEBUG_INFO 1
 #define DUMP_ENDIAN_BIG 2
@@ -185,11 +191,10 @@ bin_to_uint8(const uint8_t *bin)
   return (uint8_t)bin[0];
 }
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
-/* crc.c */
+/** @internal crc.c */
 uint16_t
 calc_crc_16_ccitt(const uint8_t *src, size_t nbytes, uint16_t crc);
 
diff --git a/include/mruby/error.h b/include/mruby/error.h
index e3e2b25e2..e9d3465c3 100644
--- a/include/mruby/error.h
+++ b/include/mruby/error.h
@@ -7,9 +7,16 @@
 #ifndef MRUBY_ERROR_H
 #define MRUBY_ERROR_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+#include "mruby/common.h"
+
+/**
+ * @file mruby/error.h
+ * @brief Error handling.
+ * @defgroup mrb_error MRuby Error handling.
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 struct RException {
   MRB_OBJECT_HEADER;
@@ -39,8 +46,7 @@ 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);
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_ERROR_H */
diff --git a/include/mruby/gc.h b/include/mruby/gc.h
index ebc57d2aa..a19378e82 100644
--- a/include/mruby/gc.h
+++ b/include/mruby/gc.h
@@ -7,16 +7,22 @@
 #ifndef MRUBY_GC_H
 #define MRUBY_GC_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+#include "mruby/common.h"
+
+/**
+ * @file mruby/gc.h
+ * @brief Uncommon memory management stuffs.
+ * @defgroup mrb_gc MRuby garbage collection.
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 typedef void (mrb_each_object_callback)(mrb_state *mrb, struct RBasic *obj, void *data);
 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);
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_GC_H */
diff --git a/include/mruby/hash.h b/include/mruby/hash.h
index 5339312c6..c52c2ec19 100644
--- a/include/mruby/hash.h
+++ b/include/mruby/hash.h
@@ -7,9 +7,16 @@
 #ifndef MRUBY_HASH_H
 #define MRUBY_HASH_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+#include "mruby/common.h"
+
+/**
+ * @file mruby/hash.h
+ * @brief Hash class
+ * @defgroup mrb_hash MRuby Hash class
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 struct RHash {
   MRB_OBJECT_HEADER;
@@ -47,8 +54,7 @@ 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*);
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_HASH_H */
diff --git a/include/mruby/irep.h b/include/mruby/irep.h
index f4061bb54..833a8adf5 100644
--- a/include/mruby/irep.h
+++ b/include/mruby/irep.h
@@ -7,12 +7,18 @@
 #ifndef MRUBY_IREP_H
 #define MRUBY_IREP_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
-
+#include "mruby/common.h"
 #include "mruby/compile.h"
 
+/**
+ * @file mruby/irep.h
+ * @brief Compiled mruby script.
+ * @defgroup mrb_irep Compiled mruby script.
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
+
 enum irep_pool_type {
   IREP_TT_STRING,
   IREP_TT_FIXNUM,
@@ -53,8 +59,7 @@ 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*);
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_IREP_H */
diff --git a/include/mruby/khash.h b/include/mruby/khash.h
index 6a4861bda..3458a2b8e 100644
--- a/include/mruby/khash.h
+++ b/include/mruby/khash.h
@@ -7,12 +7,19 @@
 #ifndef MRUBY_KHASH_H
 #define MRUBY_KHASH_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+#include <string.h>
 
 #include "mruby.h"
-#include <string.h>
+#include "mruby/common.h"
+
+/**
+ * @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
+ * @{
+ */
+MRB_BEGIN_DECL
 
 typedef uint32_t khint_t;
 typedef khint_t khiter_t;
@@ -266,8 +273,7 @@ static inline khint_t __ac_X31_hash_string(const char *s)
 
 typedef const char *kh_cstr_t;
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_KHASH_H */
diff --git a/include/mruby/numeric.h b/include/mruby/numeric.h
index 237119bf2..6dcc30a55 100644
--- a/include/mruby/numeric.h
+++ b/include/mruby/numeric.h
@@ -7,9 +7,16 @@
 #ifndef MRUBY_NUMERIC_H
 #define MRUBY_NUMERIC_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+#include "mruby/common.h"
+
+/**
+ * @file mruby/numeric.h
+ * @brief Numeric class and sub-classes of it.
+ * @defgroup mrb_string Numeric class and sub-classes of it.
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 #define POSFIXABLE(f) ((f) <= MRB_INT_MAX)
 #define NEGFIXABLE(f) ((f) >= MRB_INT_MIN)
@@ -104,8 +111,7 @@ mrb_int_sub_overflow(mrb_int minuend, mrb_int subtrahend, mrb_int *difference)
 #undef MRB_UINT_MAKE
 #undef MRB_UINT_MAKE2
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_NUMERIC_H */
diff --git a/include/mruby/proc.h b/include/mruby/proc.h
index 5441cf767..064d518b3 100644
--- a/include/mruby/proc.h
+++ b/include/mruby/proc.h
@@ -7,11 +7,17 @@
 #ifndef MRUBY_PROC_H
 #define MRUBY_PROC_H
 
+#include "mruby/common.h"
 #include "mruby/irep.h"
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+/**
+ * @file mruby/proc.h
+ * @brief Proc class
+ * @defgroup mrb_proc MRuby Proc class
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 struct REnv {
   MRB_OBJECT_HEADER;
@@ -69,8 +75,7 @@ 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)
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_PROC_H */
diff --git a/include/mruby/range.h b/include/mruby/range.h
index 079ed3bf4..4b55557e8 100644
--- a/include/mruby/range.h
+++ b/include/mruby/range.h
@@ -7,9 +7,16 @@
 #ifndef MRUBY_RANGE_H
 #define MRUBY_RANGE_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+#include "mruby/common.h"
+
+/**
+ * @file mruby/range.h
+ * @brief Range class
+ * @defgroup mrb_range MRuby Range class
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 typedef struct mrb_range_edges {
   mrb_value beg;
@@ -29,8 +36,7 @@ MRB_API mrb_value mrb_range_new(mrb_state*, mrb_value, mrb_value, mrb_bool);
 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));
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_RANGE_H */
diff --git a/include/mruby/string.h b/include/mruby/string.h
index 3c428ac54..a8239b221 100644
--- a/include/mruby/string.h
+++ b/include/mruby/string.h
@@ -1,16 +1,22 @@
-/**
- * @header mruby/string.h
- * @copyright See Copyright Notice in mruby.h
- *
- * String class
- */
+/*
+** mruby/string.h - String class
+**
+** See Copyright Notice in mruby.h
+*/
 
 #ifndef MRUBY_STRING_H
 #define MRUBY_STRING_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+#include "mruby/common.h"
+
+/**
+ * @file mruby/string.h
+ * @brief String class
+ * @defgroup mrb_string MRuby String class
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 extern const char mrb_digitmap[];
 
@@ -121,8 +127,7 @@ 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)
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_STRING_H */
diff --git a/include/mruby/value.h b/include/mruby/value.h
index 9fff3f616..0fb6703b1 100644
--- a/include/mruby/value.h
+++ b/include/mruby/value.h
@@ -7,6 +7,17 @@
 #ifndef MRUBY_VALUE_H
 #define MRUBY_VALUE_H
 
+#include "mruby/common.h"
+
+/**
+ * @file mruby/value.h
+ * @brief mrb_value functions and macros.
+ * @defgroup mrb_value mrb_value functions and macros.
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
+
 typedef uint32_t mrb_sym;
 typedef uint8_t mrb_bool;
 struct mrb_state;
@@ -226,4 +237,7 @@ 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 7785a8ce2..9aaece1d3 100644
--- a/include/mruby/variable.h
+++ b/include/mruby/variable.h
@@ -7,9 +7,16 @@
 #ifndef MRUBY_VARIABLE_H
 #define MRUBY_VARIABLE_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
+#include "mruby/common.h"
+
+/**
+ * @file mruby/variable.h
+ * @brief Functions to access mruby variables.
+ * @defgroup mrb_variable Functions to access to mruby variables.
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
 
 typedef struct global_variable {
   int   counter;
@@ -74,8 +81,7 @@ 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*);
 
-#if defined(__cplusplus)
-}  /* extern "C" { */
-#endif
+/** @} */
+MRB_END_DECL
 
 #endif  /* MRUBY_VARIABLE_H */
diff --git a/include/mruby/version.h b/include/mruby/version.h
index c2a9b6306..09be56811 100644
--- a/include/mruby/version.h
+++ b/include/mruby/version.h
@@ -7,6 +7,17 @@
 #ifndef MRUBY_VERSION_H
 #define MRUBY_VERSION_H
 
+#include "mruby/common.h"
+
+/**
+ * @file mruby/version.h
+ * @brief MRuby version macros
+ * @defgroup mrb_string MRuby version macros
+ * @ingroup MRuby
+ * @{
+ */
+MRB_BEGIN_DECL
+
 #define MRB_STRINGIZE0(expr) #expr
 #define MRB_STRINGIZE(expr) MRB_STRINGIZE0(expr)
 
@@ -39,4 +50,7 @@
   MRB_STRINGIZE(MRUBY_RELEASE_YEAR)" " \
   MRUBY_AUTHOR                         \
 
+/** @} */
+MRB_END_DECL
+
 #endif  /* MRUBY_VERSION_H */
-- 
cgit v1.2.3


From 40bf7bde785f45b46ec0dd72239822b8e9cb2a1a Mon Sep 17 00:00:00 2001
From: Seba Gamboa <me@sagmor.com>
Date: Mon, 21 Sep 2015 01:48:42 -0300
Subject: Sorting documentation grouping

---
 include/mruby.h          | 134 ++++++++++++++++++++++++++++++++---------------
 include/mruby/array.h    |   5 +-
 include/mruby/class.h    |   5 +-
 include/mruby/compile.h  |   5 +-
 include/mruby/data.h     |   5 +-
 include/mruby/debug.h    |   5 +-
 include/mruby/dump.h     |   5 +-
 include/mruby/error.h    |   5 +-
 include/mruby/gc.h       |   5 +-
 include/mruby/hash.h     |   5 +-
 include/mruby/irep.h     |   5 +-
 include/mruby/khash.h    |   5 +-
 include/mruby/numeric.h  |   8 +--
 include/mruby/proc.h     |   5 +-
 include/mruby/range.h    |   5 +-
 include/mruby/string.h   |   5 +-
 include/mruby/value.h    |   8 +--
 include/mruby/variable.h |   5 +-
 18 files changed, 131 insertions(+), 94 deletions(-)

(limited to 'include')

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
-- 
cgit v1.2.3


From dd925578c604a608f83172f85d8e5bfc3bb99c6a Mon Sep 17 00:00:00 2001
From: Seba Gamboa <me@sagmor.com>
Date: Mon, 21 Sep 2015 11:59:39 -0300
Subject: Sort compiler macros around

---
 include/mruby.h        | 70 +++++++++++++++++++++++++++++++++++---------------
 include/mruby/common.h | 53 ++++++++++++++++++++++++++++++--------
 2 files changed, 92 insertions(+), 31 deletions(-)

(limited to 'include')

diff --git a/include/mruby.h b/include/mruby.h
index 6d8b5555d..4af607b26 100644
--- a/include/mruby.h
+++ b/include/mruby.h
@@ -39,7 +39,6 @@
 
 /**
  * @file mruby.h
- * @brief Main header of mruby C API. Include this first.
  * @defgroup mruby MRuby C API
  * @{
  */
@@ -57,11 +56,13 @@ struct mrb_irep;
 struct mrb_state;
 
 /**
- * Function pointer type of custom allocator used in mrb_open_allocf.
+ * Function pointer type of custom allocator used in @ref 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.
  */
 typedef void* (*mrb_allocf) (struct mrb_state *mrb, void*, size_t, void *ud);
 
@@ -205,18 +206,6 @@ typedef struct mrb_state {
   mrb_int atexit_stack_len;
 } mrb_state;
 
-#if __STDC_VERSION__ >= 201112L
-# define mrb_noreturn _Noreturn
-#elif defined __GNUC__ && !defined __STRICT_ANSI__
-# define mrb_noreturn __attribute__((noreturn))
-# define mrb_deprecated __attribute__((deprecated))
-#elif defined _MSC_VER
-# define mrb_noreturn __declspec(noreturn)
-# define mrb_deprecated __declspec(deprecated)
-#else
-# define mrb_noreturn
-# define mrb_deprecated
-#endif
 
 typedef mrb_value (*mrb_func_t)(mrb_state *mrb, mrb_value);
 
@@ -278,8 +267,29 @@ MRB_API void mrb_define_module_function(mrb_state*, struct RClass*, const char*,
 MRB_API void mrb_define_const(mrb_state*, struct RClass*, const char *name, mrb_value);
 MRB_API void mrb_undef_method(mrb_state*, struct RClass*, const char*);
 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
+ */
 MRB_API mrb_value mrb_obj_new(mrb_state *mrb, struct RClass *c, mrb_int argc, const mrb_value *argv);
-#define mrb_class_new_instance(mrb,argc,argv,c) mrb_obj_new(mrb,c,argc,argv)
+
+/** See @ref mrb_obj_new */
+MRB_INLINE mrb_value mrb_class_new_instance(mrb_state *mrb, struct RClass *c, mrb_int argc, const mrb_value *argv) 
+{
+  return mrb_obj_new(mrb,c,argc,argv);
+}
+
 MRB_API mrb_value mrb_instance_new(mrb_state *mrb, mrb_value cv);
 MRB_API struct RClass * mrb_class_new(mrb_state *mrb, struct RClass *super);
 MRB_API struct RClass * mrb_module_new(mrb_state *mrb);
@@ -464,19 +474,32 @@ char* mrb_locale_from_utf8(const char *p, size_t len);
  */
 MRB_API mrb_state* mrb_open(void);
 
-
 /**
- * Create new mrb_state with custom allocator.
+ * Create new mrb_state with custom allocators.
  *
+ * @param f
+ *      Reference to the allocation function.
  * @param ud
- *      will be passed to custom allocator f. If user data isn't required just
- *      pass NULL. Function pointer f must satisfy requirements of its type.
+ *      User data will be passed to custom allocator f.
+ *      If user data isn't required just pass NULL.
+ * @returns
+ *      Pointer to the newly created mrb_state.
+ */
+MRB_API mrb_state* mrb_open_allocf(mrb_allocf f, void *ud);
+
+/**
+ * Create new mrb_state with just the MRuby core
  *
+ * @param f
+ *      Reference to the allocation function.
+ *      Use mrb_default_allocf for the default
+ * @param ud
+ *      User data will be passed to custom allocator f.
+ *      If user data isn't required just pass NULL.
  * @returns
  *      Pointer to the newly created mrb_state.
  */
-MRB_API mrb_state* mrb_open_allocf(mrb_allocf, void *ud);
-MRB_API mrb_state* mrb_open_core(mrb_allocf, void *ud);
+MRB_API mrb_state* mrb_open_core(mrb_allocf f, void *ud);
 
 /**
  * Closes and frees a mrb_state.
@@ -486,6 +509,11 @@ MRB_API mrb_state* mrb_open_core(mrb_allocf, void *ud);
  */
 MRB_API void mrb_close(mrb_state *mrb);
 
+/**
+ * The default allocation function.
+ *
+ * @ref mrb_allocf
+ */
 MRB_API void* mrb_default_allocf(mrb_state*, void*, size_t, void*);
 
 MRB_API mrb_value mrb_top_self(mrb_state *);
diff --git a/include/mruby/common.h b/include/mruby/common.h
index 0a7cd2f1e..01e558291 100644
--- a/include/mruby/common.h
+++ b/include/mruby/common.h
@@ -7,29 +7,62 @@
 #ifndef MRUBY_COMMON_H
 #define MRUBY_COMMON_H
 
+/**
+ * @file mruby/common.h
+ * @defgroup mruby_common Shared compiler macros
+ * @ingroup mruby
+ * @{
+ */
+
 #ifdef __cplusplus
-/** Start declarations in C++ mode */
-#define MRB_BEGIN_DECL extern "C" {
-/** End declarations in C++ mode */
-#define MRB_END_DECL	}
+# define MRB_BEGIN_DECL extern "C" {
+# define MRB_END_DECL	}
 #else
 /** Start declarations in C mode */
-#define MRB_BEGIN_DECL /* empty */
+# define MRB_BEGIN_DECL
 /** End declarations in C mode */
-#define MRB_END_DECL	/* empty */
+# define MRB_END_DECL
+#endif
+
+/** Declare a function that never returns. */
+#if __STDC_VERSION__ >= 201112L
+# define mrb_noreturn _Noreturn
+#elif defined __GNUC__ && !defined __STRICT_ANSI__
+# define mrb_noreturn __attribute__((noreturn))
+#elif defined _MSC_VER
+# define mrb_noreturn __declspec(noreturn)
+#else
+# define mrb_noreturn
+#endif
+
+/** Mark a function as deprecated. */
+#if defined __GNUC__ && !defined __STRICT_ANSI__
+# define mrb_deprecated __attribute__((deprecated))
+#elif defined _MSC_VER
+# define mrb_deprecated __declspec(deprecated)
+#else
+# define mrb_deprecated
+#endif
+
+/** Declare a function as always inlined. */
+#if defined(_MSC_VER)
+# define MRB_INLINE static __inline
+#else
+# define MRB_INLINE static inline
 #endif
 
 
+/** Declare a public MRuby API function. */
 #if defined(MRB_BUILD_AS_DLL)
 #if defined(MRB_CORE) || defined(MRB_LIB)
-#define MRB_API __declspec(dllexport)
+# define MRB_API __declspec(dllexport)
 #else
-#define MRB_API __declspec(dllimport)
+# define MRB_API __declspec(dllimport)
 #endif
 #else
-#define MRB_API extern
+# define MRB_API extern
 #endif
 
-MRB_END_DECL
+/** @} */
 
 #endif  /* MRUBY_COMMON_H */
-- 
cgit v1.2.3


From 0e5b81539990a6b87913ed73cb37f0640a39e5a6 Mon Sep 17 00:00:00 2001
From: Seba Gamboa <me@sagmor.com>
Date: Mon, 21 Sep 2015 14:50:04 -0300
Subject: Document data header

---
 include/mruby/data.h | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

(limited to 'include')

diff --git a/include/mruby/data.h b/include/mruby/data.h
index 8fd798455..c68b050f7 100644
--- a/include/mruby/data.h
+++ b/include/mruby/data.h
@@ -11,14 +11,23 @@
 
 /**
  * @file mruby/data.h
- * @defgroup mruby_data User defined objects.
+ * @defgroup mruby_data Custom C wrapped data.
+ *
+ * Defining Ruby wrappers around native objects.
+ *
  * @ingroup mruby
  * @{
  */
 MRB_BEGIN_DECL
 
+/**
+ * Custom data type description.
+ */
 typedef struct mrb_data_type {
+  /** data type name */
   const char *struct_name;
+
+  /** data type release function pointer */
   void (*dfree)(mrb_state *mrb, void*);
 } mrb_data_type;
 
-- 
cgit v1.2.3


From 88f9770f831eccab9239ca8b7b812170455e62ce Mon Sep 17 00:00:00 2001
From: Seba Gamboa <me@sagmor.com>
Date: Mon, 21 Sep 2015 14:50:59 -0300
Subject: document mrb_nil_value

---
 include/mruby/value.h | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

(limited to 'include')

diff --git a/include/mruby/value.h b/include/mruby/value.h
index e257c6b8c..d9614f356 100644
--- a/include/mruby/value.h
+++ b/include/mruby/value.h
@@ -176,8 +176,14 @@ mrb_obj_value(void *p)
   return v;
 }
 
-static inline mrb_value
-mrb_nil_value(void)
+
+/**
+ * Get a nil mrb_value object.
+ *
+ * @return
+ *      nil mrb_value object reference.
+ */
+MRB_INLINE mrb_value mrb_nil_value(void)
 {
   mrb_value v;
   SET_NIL_VALUE(v);
-- 
cgit v1.2.3


From 4c8205db1f364e0cad82ea7d7a2b3ac1b566078c Mon Sep 17 00:00:00 2001
From: Seba Gamboa <me@sagmor.com>
Date: Mon, 21 Sep 2015 15:13:43 -0300
Subject: Merge descriptions from doc/api/mruby/array.h.md

---
 include/mruby/array.h | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 80 insertions(+), 1 deletion(-)

(limited to 'include')

diff --git a/include/mruby/array.h b/include/mruby/array.h
index ca92486d6..e716c883d 100644
--- a/include/mruby/array.h
+++ b/include/mruby/array.h
@@ -17,6 +17,7 @@
  */
 MRB_BEGIN_DECL
 
+
 typedef struct mrb_shared_array {
   int refcnt;
   mrb_int len;
@@ -47,15 +48,93 @@ struct RArray {
 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
+ */
 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);
-MRB_API void mrb_ary_push(mrb_state*, mrb_value, 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
+ */
+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.
+ */
 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.
+ */
 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.
+ */
 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);
 MRB_API mrb_value mrb_check_array_type(mrb_state *mrb, mrb_value self);
 MRB_API mrb_value mrb_ary_unshift(mrb_state *mrb, mrb_value self, mrb_value item);
-- 
cgit v1.2.3