Merge pull request #2416 from take-cheeze/c_api_ref

Start documenting C APIs.

2 files changed, 99 insertions, 0 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
new file mode 100644
index 000000000..131e50515
--- /dev/null
+++ b/doc/api/README.md
@@ -0,0 +1,30 @@
+# C API Reference
+
+This is a C API Reference.
+The structure of this document will follow the directory structure of `include/` directory.
+
+## Headers list
+Header name|Features
+-----------|--------
+[mrbconf.h](../mrbconf/README.md)|Defines macros for mruby configurations.
+[mruby.h](./mruby.h.md)|Main header of mruby C API. Include this first.
+[mruby/array.h](./mruby.array.h.md)|`Array` class.
+[mruby/class.h](./mruby.class.h.md)|`Class` class.
+[mruby/compile.h](./mruby.compile.h.md)|mruby compiler.
+[mruby/data.h](./mruby.data.h.md)|User defined object.
+[mruby/debug.h](./mruby.debug.h.md)|Debugging.
+[mruby/dump.h](./mruby.dump.h.md)|Dumping compiled mruby script.
+[mruby/error.h](./mruby.error.h.md)|Error handling.
+[mruby/gc.h](./mruby.gc.h.md)|Uncommon memory management stuffs.
+[mruby/hash.h](./mruby.hash.h.md)|`Hash` class.
+[mruby/irep.h](./mruby.irep.h.md)|Compiled mruby script.
+[mruby/khash.h](./mruby.khash.h.md)|Defines of khash which is used in hash table of mruby.
+[mruby/numeric.h](./mruby.numeric.h.md)|`Numeric` class and sub-classes of it.
+[mruby/opode.h](./mruby.opcode.h.md)|Operation codes used in mruby VM.
+[mruby/proc.h](./mruby.proc.h.md)|`Proc` class.
+[mruby/range.h](./mruby.range.h.md)|`Range` class.
+[mruby/re.h](./mruby.re.h.md)|`Regexp` class.
+[mruby/string.h](./mruby.string.h.md)|`String` class.
+[mruby/value.h](./mruby.value.h.md)|`mrb_value` functions and macros.
+[mruby/variable.h](./mruby.variable.h.md)|Functions to access to mruby variables.
+[mruby/version.h](./mruby.version.h.md)|Macros of mruby version.
diff --git a/doc/api/mruby.h.md b/doc/api/mruby.h.md
new file mode 100644
index 000000000..bd844a749
--- /dev/null
+++ b/doc/api/mruby.h.md
@@ -0,0 +1,69 @@
+# mruby.h
+
+Basic header of mruby.
+It includes **mrbconf.h**, **mruby/value.h**, **mruby/version.h** internally.
+
+## `mrb_state` management
+
+### mrb_open
+```C
+mrb_state* mrb_open();
+```
+Creates new `mrb_state`.
+
+### mrb_allocf
+```C
+typedef void* (*mrb_allocf) (struct mrb_state *mrb, void *ptr, size_t s, void *ud);
+```
+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.
+
+### mrb_open_allocf
+```C
+mrb_state* mrb_open_allocf(mrb_allocf f, void *ud);
+```
+Create new `mrb_state` with custom allocator.
+`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_close
+```C
+void mrb_close(mrb_state *mrb);
+```
+Deletes `mrb_state`.
+
+## Method
+
+### mrb_get_args
+```C
+int mrb_get_args(mrb_state *mrb, const char *format, ...);
+```
+Retrieve arguments from `mrb_state`.
+Use it inside a function pointed by `mrb_func_t`.
+It returns number of function retrieved.
+`format` is a list of following format specifier:
+
+char|mruby type|retrieve types|note
+:---:|----------|--------------|---
+`o`|`Object`|`mrb_value`|Could be used to retreive any type of argument
+`C`|`Class`/`Module`|`mrb_value`|
+`S`|`String`|`mrb_value`|
+`A`|`Array`|`mrb_value`|
+`H`|`Hash`|`mrb_value`|
+`s`|`String`|`char*`, `mrb_int`|
+`z`|`String`|`char*`|
+`a`|`Array`|`mrb_value*`, `mrb_int`|
+`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.
+<code>&#124;</code>|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.
+
+The passing variadic arguments must be a pointer of retreiving type.