Merge pull request #2999 from sagmor/better-docs

More Docs

3 files changed, 86 insertions, 28 deletions

diff --git a/include/mruby.h b/include/mruby.h
index b0161aff7..2338f66ac 100644
--- a/include/mruby.h
+++ b/include/mruby.h
@@ -574,42 +574,45 @@ MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *o
 #define MRB_ARGS_NONE()     ((mrb_aspec)0)
 
 /**
- * Format specifiers for \ref mrb_get_args function
- *
- * 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. |
+ * Format specifiers for {mrb_get_args} function
+ *
+ * Must be a C string composed of the following format specifiers:
+ *
+ * | char | Ruby type      | C types           | Notes                                               |
+ * |:----:|----------------|-------------------|----------------------------------------------------|
+ * | `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 *            | `NULL` 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. |
+ *
+ * @see mrb_get_args
  */
 typedef const char *mrb_args_format;
 
 /**
  * Retrieve arguments from mrb_state.
  *
- * When applicable, implicit conversions (such as to_str, to_ary, to_hash) are
+ * 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.
+ * Used inside a function of mrb_func_t type.
  *
  * @param mrb The current MRuby state.
- * @param format is a list of format specifiers see @ref mrb_args_format
+ * @param format [mrb_args_format] is a list of format specifiers
  * @param ... The passing variadic arguments must be a pointer of retrieving type.
  * @return the number of arguments retrieved.
+ * @see mrb_args_format
  */
 MRB_API mrb_int mrb_get_args(mrb_state *mrb, mrb_args_format format, ...);
 
@@ -726,7 +729,7 @@ MRB_API void mrb_close(mrb_state *mrb);
 /**
  * The default allocation function.
  *
- * @ref mrb_allocf
+ * @see mrb_allocf
  */
 MRB_API void* mrb_default_allocf(mrb_state*, void*, size_t, void*);
 
@@ -854,9 +857,26 @@ MRB_API mrb_value mrb_attr_get(mrb_state *mrb, mrb_value obj, mrb_sym id);
 MRB_API mrb_bool mrb_respond_to(mrb_state *mrb, mrb_value obj, mrb_sym mid);
 MRB_API mrb_bool mrb_obj_is_instance_of(mrb_state *mrb, mrb_value obj, struct RClass* c);
 
-/* fiber functions (you need to link mruby-fiber mrbgem to use) */
+
+/*
+ * Resume a Fiber
+ *
+ * @mrbgem mruby-fiber
+ */
 MRB_API mrb_value mrb_fiber_resume(mrb_state *mrb, mrb_value fib, mrb_int argc, const mrb_value *argv);
+
+/*
+ * Yield a Fiber
+ *
+ * @mrbgem mruby-fiber
+ */
 MRB_API mrb_value mrb_fiber_yield(mrb_state *mrb, mrb_int argc, const mrb_value *argv);
+
+/*
+ * FiberError reference
+ *
+ * @mrbgem mruby-fiber
+ */
 #define E_FIBER_ERROR (mrb_class_get(mrb, "FiberError"))
 
 /* memory pool implementation */
diff --git a/include/mruby/error.h b/include/mruby/error.h
index 8b6430137..1ac0791a2 100644
--- a/include/mruby/error.h
+++ b/include/mruby/error.h
@@ -32,12 +32,34 @@ MRB_API mrb_noreturn void mrb_no_method_error(mrb_state *mrb, mrb_sym id, mrb_va
 /* declaration for fail method */
 MRB_API mrb_value mrb_f_raise(mrb_state*, mrb_value);
 
-/* functions defined in mruby-error mrbgem */
+/**
+ * Protect
+ *
+ * @mrbgem mruby-error
+ */
 MRB_API mrb_value mrb_protect(mrb_state *mrb, mrb_func_t body, mrb_value data, mrb_bool *state);
+
+/**
+ * Ensure
+ *
+ * @mrbgem mruby-error
+ */
 MRB_API mrb_value mrb_ensure(mrb_state *mrb, mrb_func_t body, mrb_value b_data,
                              mrb_func_t ensure, mrb_value e_data);
+
+/**
+ * Rescue
+ *
+ * @mrbgem mruby-error
+ */
 MRB_API mrb_value mrb_rescue(mrb_state *mrb, mrb_func_t body, mrb_value b_data,
                              mrb_func_t rescue, mrb_value r_data);
+
+/**
+ * Rescue exception
+ *
+ * @mrbgem mruby-error
+ */
 MRB_API mrb_value mrb_rescue_exceptions(mrb_state *mrb, mrb_func_t body, mrb_value b_data,
                                         mrb_func_t rescue, mrb_value r_data,
                                         mrb_int len, struct RClass **classes);
diff --git a/include/mruby/value.h b/include/mruby/value.h
index dfad3ec73..002ea8511 100644
--- a/include/mruby/value.h
+++ b/include/mruby/value.h
@@ -98,6 +98,22 @@ enum mrb_vtype {
 
 #include "mruby/object.h"
 
+#ifdef MRB_DOCUMENTATION_BLOCK
+
+/**
+ * @abstract
+ * MRuby value boxing.
+ *
+ * Actual implementation depends on configured boxing type.
+ *
+ * @see mruby/boxing_no.h Default boxing representation
+ * @see mruby/boxing_word.h Word representation
+ * @see mruby/boxing_nan.h Boxed double representation
+ */
+typedef void mrb_value;
+
+#endif
+
 #if defined(MRB_NAN_BOXING)
 #include "boxing_nan.h"
 #elif defined(MRB_WORD_BOXING)