summaryrefslogtreecommitdiffhomepage
path: root/include
diff options
context:
space:
mode:
Diffstat (limited to 'include')
-rw-r--r--include/mruby.h134
-rw-r--r--include/mruby/array.h5
-rw-r--r--include/mruby/class.h5
-rw-r--r--include/mruby/compile.h5
-rw-r--r--include/mruby/data.h5
-rw-r--r--include/mruby/debug.h5
-rw-r--r--include/mruby/dump.h5
-rw-r--r--include/mruby/error.h5
-rw-r--r--include/mruby/gc.h5
-rw-r--r--include/mruby/hash.h5
-rw-r--r--include/mruby/irep.h5
-rw-r--r--include/mruby/khash.h5
-rw-r--r--include/mruby/numeric.h8
-rw-r--r--include/mruby/proc.h5
-rw-r--r--include/mruby/range.h5
-rw-r--r--include/mruby/string.h5
-rw-r--r--include/mruby/value.h8
-rw-r--r--include/mruby/variable.h5
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
generated by cgit v1.2.3 (git 2.39.1) at 2026-04-15 01:56:29 +0000