Setting up doxygen groups

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

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

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

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

include/mruby/common.h

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

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

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

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

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

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

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

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

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

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

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

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

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

include/mruby/string.h

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

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

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

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