Merge pull request #4636 from davidsiaw/doxygen

Generate doxygen docs for mruby

.gitignore

@@ -30,5 +30,6 @@ tags
 /benchmark/*.png
 
 /doc/api
+/doxygen/
 
 /src/y.tab.c

Makefile

@@ -2,6 +2,8 @@
 # We provide a minimalistic version called minirake inside of our
 # codebase.
 
+-include Makefile.doc
+
 RAKE = ruby ./minirake
 
 all :
@@ -12,6 +14,6 @@ test : all
 	$(RAKE) test
 .PHONY : test
 
-clean :
+clean : docsclean
 	$(RAKE) clean
 .PHONY : clean

Makefile.doc

+SRCS=$(shell find src -name '*.c')
+HEADERS=$(shell find include -name '*.h')
+MDDOCS=$(shell find doc -name '*.md')
+
+doxygen : Doxyfile $(SRCS) $(HEADERS) $(MDDOCS)
+	doxygen Doxyfile
+
+docs : doxygen
+
+docserver : docs
+	firefox doxygen/html/index.html 
+
+docsclean :
+	rm -r doxygen
+.PHONY : docserver docsclean

doc/guides/compile.md

@@ -6,11 +6,11 @@ binaries.
 ## Prerequisites
 
 To compile mruby out of the source code you need the following tools:
-* C Compiler (e.g. ```gcc```)
-* Linker (e.g. ```gcc```)
-* Archive utility (e.g. ```ar```)
-* Parser generator (e.g. ```bison```)
-* Ruby 2.0 or later (e.g. ```ruby``` or ```jruby```)
+* C Compiler (e.g. `gcc`)
+* Linker (e.g. `gcc`)
+* Archive utility (e.g. `ar`)
+* Parser generator (e.g. `bison`)
+* Ruby 2.0 or later (e.g. `ruby` or `jruby`)
 
 Optional:
 * GIT (to update mruby source and integrate mrbgems easier)
@@ -32,10 +32,10 @@ All tools necessary to compile mruby can be set or modified here. In case
 you want to maintain an additional *build_config.rb* you can define a
 customized path using the *$MRUBY_CONFIG* environment variable.
 
-To compile just call ```./minirake``` inside of the mruby source root. To
-generate and execute the test tools call ```./minirake test```. To clean
-all build files call ```./minirake clean```. To see full command line on
-build, call ```./minirake -v```.
+To compile just call `./minirake` inside of the mruby source root. To
+generate and execute the test tools call `./minirake test`. To clean
+all build files call `./minirake clean`. To see full command line on
+build, call `./minirake -v`.
 
 ## Build Configuration
 
@@ -79,7 +79,7 @@ toolchain :android
 ```
 
 Requires the custom standalone Android NDK and the toolchain path
-in ```ANDROID_STANDALONE_TOOLCHAIN```.
+in `ANDROID_STANDALONE_TOOLCHAIN`.
 
 ### Binaries
 
@@ -97,7 +97,7 @@ conf.gem "#{root}/mrbgems/mruby-bin-mirb"
 ### File Separator
 
 Some environments require a different file separator character. It is possible to
-set the character via ```conf.file_separator```.
+set the character via `conf.file_separator`.
 ```ruby
 conf.file_separator = '/'
 ```
@@ -119,7 +119,7 @@ end
 
 C Compiler has header searcher to detect installed library.
 
-If you need a include path of header file use ```search_header_path```:
+If you need a include path of header file use `search_header_path`:
 ```ruby
 # Searches ```iconv.h```.
 # If found it will return include path of the header file.
@@ -127,7 +127,7 @@ If you need a include path of header file use ```search_header_path```:
 fail 'iconv.h not found' unless conf.cc.search_header_path 'iconv.h'
 ```
 
-If you need a full file name of header file use ```search_header```:
+If you need a full file name of header file use `search_header`:
 ```ruby
 # Searches ```iconv.h```.
 # If found it will return full path of the header file.
@@ -136,11 +136,11 @@ iconv_h = conf.cc.search_header 'iconv.h'
 print "iconv.h found: #{iconv_h}\n"
 ```
 
-Header searcher uses compiler's ```include_paths``` by default.
+Header searcher uses compiler's `include_paths` by default.
 When you are using GCC toolchain (including clang toolchain since its base is gcc toolchain)
-it will use compiler specific include paths too. (For example ```/usr/local/include```, ```/usr/include```)
+it will use compiler specific include paths too. (For example `/usr/local/include`, `/usr/include`)
 
-If you need a special header search paths define a singleton method ```header_search_paths``` to C compiler:
+If you need a special header search paths define a singleton method `header_search_paths` to C compiler:
 ```ruby
 def conf.cc.header_search_paths
   ['/opt/local/include'] + include_paths
@@ -222,7 +222,7 @@ See doc/mrbgems/README.md for more option about mrbgems.
 
 Configuration Mrbtest build process.
 
-If you want mrbtest.a only, You should set ```conf.build_mrbtest_lib_only```
+If you want mrbtest.a only, You should set `conf.build_mrbtest_lib_only`
 ```ruby
 conf.build_mrbtest_lib_only
 ```
@@ -230,9 +230,9 @@ conf.build_mrbtest_lib_only
 ### Bintest
 
 Tests for mrbgem tools using CRuby.
-To have bintests place \*.rb scripts to ```bintest/``` directory of mrbgems.
-See ```mruby-bin-*/bintest/*.rb``` if you need examples.
-If you want a temporary files use `tempfile` module of CRuby instead of ```/tmp/```.
+To have bintests place \*.rb scripts to `bintest/` directory of mrbgems.
+See `mruby-bin-*/bintest/*.rb` if you need examples.
+If you want a temporary files use `tempfile` module of CRuby instead of `/tmp/`.
 
 You can enable it with following:
 ```ruby
@@ -247,8 +247,8 @@ correctly. To support mrbgems written in C++, mruby can be
 configured to use C++ exception.
 
 There are two levels of C++ exception handling. The one is
-```enable_cxx_exception``` that enables C++ exception, but
-uses C ABI. The other is ```enable_cxx_abi``` where all
+`enable_cxx_exception` that enables C++ exception, but
+uses C ABI. The other is `enable_cxx_abi` where all
 files are compiled by C++ compiler.
 
 When you mix C++ code, C++ exception would be enabled automatically.
@@ -266,7 +266,7 @@ C++ exception, add following:
 conf.disable_cxx_exception
 ```
 and you will get an error when you try to use C++ gem.
-Note that it must be called before ```enable_cxx_exception``` or ```gem``` method.
+Note that it must be called before `enable_cxx_exception` or `gem` method.
 
 ### Debugging mode
 
@@ -276,17 +276,17 @@ conf.enable_debug
 ```
 
 When debugging mode is enabled
-* Macro ```MRB_DEBUG``` would be defined.
-	* Which means ```mrb_assert()``` macro is enabled.
-* Debug information of irep would be generated by ```mrbc```.
-	* Because ```-g``` flag would be added to ```mrbc``` runner.
+* Macro `MRB_DEBUG` would be defined.
+	* Which means `mrb_assert()` macro is enabled.
+* Debug information of irep would be generated by `mrbc`.
+	* Because `-g` flag would be added to `mrbc` runner.
     * You can have better backtrace of mruby scripts with this.
 
 ## Cross-Compilation
 
 mruby can also be cross-compiled from one platform to another. To
 achieve this the *build_config.rb* needs to contain an instance of
-```MRuby::CrossBuild```. This instance defines the compilation
+`MRuby::CrossBuild`. This instance defines the compilation
 tools and flags for the target platform. An example could look
 like this:
 ```ruby
@@ -298,12 +298,12 @@ MRuby::CrossBuild.new('32bit') do |conf|
 end
 ```
 
-All configuration options of ```MRuby::Build``` can also be used
-in ```MRuby::CrossBuild```.
+All configuration options of `MRuby::Build` can also be used
+in `MRuby::CrossBuild`.
 
 ### Mrbtest in Cross-Compilation
 
-In cross compilation, you can run ```mrbtest``` on emulator if
+In cross compilation, you can run `mrbtest` on emulator if
 you have it by changing configuration of test runner.
 ```ruby
 conf.test_runner do |t|
@@ -350,15 +350,15 @@ in *build/host/src*)
 result will be stored in *build/host/src/y.tab.c*)
 * compile  *build/host/src/y.tab.c* to  *build/host/src/y.tab.o*
 * create *build/host/lib/libmruby_core.a* out of all object files (C only)
-* create ```build/host/bin/mrbc``` by compiling *tools/mrbc/mrbc.c* and
+* create `build/host/bin/mrbc` by compiling *tools/mrbc/mrbc.c* and
 linking with *build/host/lib/libmruby_core.a*
 * create *build/host/mrblib/mrblib.c* by compiling all \*.rb files
-under *mrblib* with ```build/host/bin/mrbc```
+under *mrblib* with `build/host/bin/mrbc`
 * compile *build/host/mrblib/mrblib.c* to *build/host/mrblib/mrblib.o*
 * create *build/host/lib/libmruby.a* out of all object files (C and Ruby)
-* create ```build/host/bin/mruby``` by compiling *mrbgems/mruby-bin-mruby/tools/mruby/mruby.c* and
+* create `build/host/bin/mruby` by compiling *mrbgems/mruby-bin-mruby/tools/mruby/mruby.c* and
 linking with *build/host/lib/libmruby.a*
-* create ```build/host/bin/mirb``` by compiling *mrbgems/mruby-bin-mirb/tools/mirb/mirb.c* and
+* create `build/host/bin/mirb` by compiling *mrbgems/mruby-bin-mirb/tools/mirb/mirb.c* and
 linking with *build/host/lib/libmruby.a*
 
 ```
@@ -427,15 +427,15 @@ in *build/i386/src*)
 result will be stored in *build/i386/src/y.tab.c*)
 * cross-compile *build/i386/src/y.tab.c* to *build/i386/src/y.tab.o*
 * create *build/i386/mrblib/mrblib.c* by compiling all \*.rb files
-under *mrblib* with the native ```build/host/bin/mrbc```
+under *mrblib* with the native `build/host/bin/mrbc`
 * cross-compile *build/host/mrblib/mrblib.c* to *build/host/mrblib/mrblib.o*
 * create *build/i386/lib/libmruby.a* out of all object files (C and Ruby)
-* create ```build/i386/bin/mruby``` by cross-compiling *mrbgems/mruby-bin-mruby/tools/mruby/mruby.c* and
+* create `build/i386/bin/mruby` by cross-compiling *mrbgems/mruby-bin-mruby/tools/mruby/mruby.c* and
 linking with *build/i386/lib/libmruby.a*
-* create ```build/i386/bin/mirb``` by cross-compiling *mrbgems/mruby-bin-mirb/tools/mirb/mirb.c* and
+* create `build/i386/bin/mirb` by cross-compiling *mrbgems/mruby-bin-mirb/tools/mirb/mirb.c* and
 linking with *build/i386/lib/libmruby.a*
 * create *build/i386/lib/libmruby_core.a* out of all object files (C only)
-* create ```build/i386/bin/mrbc``` by cross-compiling *tools/mrbc/mrbc.c* and
+* create `build/i386/bin/mrbc` by cross-compiling *tools/mrbc/mrbc.c* and
 linking with *build/i386/lib/libmruby_core.a*
 
 ```
@@ -482,7 +482,7 @@ all usages of stdio and doesn't compile any binaries (e.g. mrbc).
 ## Test Environment
 
 mruby's build process includes a test environment. In case you start the testing
-of mruby, a native binary called ```mrbtest``` will be generated and executed.
+of mruby, a native binary called `mrbtest` will be generated and executed.
 This binary contains all test cases which are defined under *test/t*. In case
 of a cross-compilation an additional cross-compiled *mrbtest* binary is
 generated. You can copy this binary and run on your target system.

doc/limitations.md

@@ -14,17 +14,17 @@ This document does not contain a complete list of limitations.
 Please help to improve it by submitting your findings.
 
 
-## ```1/2``` gives ```0.5```
+## `1/2` gives `0.5`
 
-Since mruby does not have ```Bignum```, bigger integers are represented
-by ```Float``` numbers. To enhance interoperability between ```Fixnum```
-and ```Float```, mruby provides ```Float#upto``` and other iterating
-methods for the ```Float``` class.  As a side effect, ```1/2``` gives ```0.5```
-not ```0```.
+Since mruby does not have `Bignum`, bigger integers are represented
+by `Float` numbers. To enhance interoperability between `Fixnum`
+and `Float`, mruby provides `Float#upto` and other iterating
+methods for the `Float` class.  As a side effect, `1/2` gives `0.5`
+not `0`.
 
-## ```Array``` passed to ```puts```
+## `Array` passed to `puts`
 
-Passing an Array to ```puts``` results in different output.
+Passing an Array to `puts` results in different output.
 
 ```ruby
 puts [1,2,3]
@@ -44,9 +44,9 @@ puts [1,2,3]
 [1, 2, 3]
 ```
 
-## ```Kernel.raise``` in rescue clause
+## `Kernel.raise` in rescue clause
 
-```Kernel.raise``` without arguments does not raise the current exception within
+`Kernel.raise` without arguments does not raise the current exception within
 a rescue clause.
 
 ```ruby
@@ -59,7 +59,7 @@ end
 
 #### Ruby [ruby 2.0.0p645 (2015-04-13 revision 50299)]
 
-```ZeroDivisionError``` is raised.
+`ZeroDivisionError` is raised.
 
 #### mruby [2.0.1 (2019-4-4)]
 
@@ -67,13 +67,13 @@ No exception is raised.
 
 ## Fiber execution can't cross C function boundary
 
-mruby's ```Fiber``` is implemented in a similar way to Lua's co-routine. This
+mruby's `Fiber` is implemented in a similar way to Lua's co-routine. This
 results in the consequence that you can't switch context within C functions.
-Only exception is ```mrb_fiber_yield``` at return.
+Only exception is `mrb_fiber_yield` at return.
 
-## ```Array``` does not support instance variables
+## `Array` does not support instance variables
 
-To reduce memory consumption ```Array``` does not support instance variables.
+To reduce memory consumption `Array` does not support instance variables.
 
 ```ruby
 class Liste < Array
@@ -87,11 +87,11 @@ p Liste.new "foobar"
 
 #### Ruby [ruby 2.0.0p645 (2015-04-13 revision 50299)]
 
-``` [] ```
+` [] `
 
 #### mruby [2.0.1 (2019-4-4)]
 
-```ArgumentError``` is raised.
+`ArgumentError` is raised.
 
 ## Method visibility
 
@@ -128,8 +128,8 @@ true
 
 ## defined?
 
-The ```defined?``` keyword is considered too complex to be fully
-implemented. It is recommended to use ```const_defined?``` and
+The `defined?` keyword is considered too complex to be fully
+implemented. It is recommended to use `const_defined?` and
 other reflection methods instead.
 
 ```ruby
@@ -144,9 +144,9 @@ nil
 
 #### mruby [2.0.1 (2019-4-4)]
 
-```NameError``` is raised.
+`NameError` is raised.
 
-## ```alias``` on global variables
+## `alias` on global variables
 
 Aliasing a global variable works in CRuby but is not part
 of the ISO standard.
@@ -157,7 +157,7 @@ alias $a $__a__
 
 #### Ruby [ruby 2.0.0p645 (2015-04-13 revision 50299)]
 
-``` nil ```
+` nil `
 
 #### mruby [2.0.1 (2019-4-4)]
 
@@ -178,12 +178,12 @@ end
 
 #### Ruby [ruby 2.0.0p645 (2015-04-13 revision 50299)]
 
-```ArgumentError``` is raised.
-The re-defined ```+``` operator does not accept any arguments.
+`ArgumentError` is raised.
+The re-defined `+` operator does not accept any arguments.
 
 #### mruby [2.0.1 (2019-4-4)]
 
-``` 'ab' ```
+` 'ab' `
 Behavior of the operator wasn't changed.
 
 ## Kernel#binding is not supported

include/mruby.h

@@ -25,6 +25,10 @@
 ** [ MIT license: http://www.opensource.org/licenses/mit-license.php ]
 */
 
+/**
+ * @file mruby.h
+ */
+
 #ifndef MRUBY_H
 #define MRUBY_H
 
@@ -97,11 +101,14 @@ MRB_BEGIN_DECL
 typedef uint8_t mrb_code;
 
 /**
- * Required arguments signature type.
+ * \class mrb_aspec
+ *
+ * Specifies the number of arguments a function takes
+ *
+ * Example: `MRB_ARGS_REQ(2) | MRB_ARGS_OPT(1)` for a method that expects 2..3 arguments
  */
 typedef uint32_t mrb_aspec;
 
-
 struct mrb_irep;
 struct mrb_state;
 

include/mruby/array.h

-/*
-** mruby/array.h - Array class
+/**
+** @file mruby/array.h - Array class
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/boxing_nan.h

-/*
-** mruby/boxing_nan.h - nan boxing mrb_value definition
+/**
+** @file mruby/boxing_nan.h - nan boxing mrb_value definition
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/boxing_no.h

-/*
-** mruby/boxing_no.h - unboxed mrb_value definition
+/**
+** @file mruby/boxing_no.h - unboxed mrb_value definition
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/boxing_word.h

-/*
-** mruby/boxing_word.h - word boxing mrb_value definition
+/**
+** @file mruby/boxing_word.h - word boxing mrb_value definition
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/class.h

-/*
-** mruby/class.h - Class class
+/**
+** @file mruby/class.h - Class class
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/common.h

-/*
-**"common.h - mruby common platform definition"
+/**
+** @file common.h - mruby common platform definition"
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/compile.h

-/*
-** mruby/compile.h - mruby parser
+/**
+** @file mruby/compile.h - mruby parser
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/data.h

-/*
-** mruby/data.h - Data class
+/**
+** @file mruby/data.h - Data class
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/debug.h

-/*
-** mruby/debug.h - mruby debug info
+/**
+** @file mruby/debug.h - mruby debug info
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/dump.h

-/*
-** mruby/dump.h - mruby binary dumper (mrbc binary format)
+/**
+** @file mruby/dump.h - mruby binary dumper (mrbc binary format)
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/error.h

-/*
-** mruby/error.h - Exception class
+/**
+** @file mruby/error.h - Exception class
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/gc.h

-/*
-** mruby/gc.h - garbage collector for mruby
+/**
+** @file mruby/gc.h - garbage collector for mruby
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/hash.h

-/*
-** mruby/hash.h - Hash class
+/**
+** @file mruby/hash.h - Hash class
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/irep.h

-/*
-** mruby/irep.h - mrb_irep structure
+/**
+** @file mruby/irep.h - mrb_irep structure
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/istruct.h

-/*
-** mruby/istruct.h - Inline structures
+/**
+** @file mruby/istruct.h - Inline structures
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/khash.h

-/*
-** mruby/khash.c - Hash for mruby
+/**
+** @file mruby/khash.h - Hash for mruby
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/numeric.h

-/*
-** mruby/numeric.h - Numeric, Integer, Float, Fixnum class
+/**
+** @file mruby/numeric.h - Numeric, Integer, Float, Fixnum class
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/object.h

-/*
-** mruby/object.h - mruby object definition
+/**
+** @file mruby/object.h - mruby object definition
 **
 ** See Copyright Notice in mruby.h
 */
@@ -8,15 +8,14 @@
 #define MRUBY_OBJECT_H
 
 #define MRB_OBJECT_HEADER \
-  enum mrb_vtype tt:8;\
-  uint32_t color:3;\
-  uint32_t flags:21;\
-  struct RClass *c;\
+  enum mrb_vtype tt:8;    \
+  uint32_t color:3;       \
+  uint32_t flags:21;      \
+  struct RClass *c;       \
   struct RBasic *gcnext
 
 #define MRB_FLAG_TEST(obj, flag) ((obj)->flags & (flag))
 
-
 struct RBasic {
   MRB_OBJECT_HEADER;
 };

include/mruby/opcode.h

-/*
-** mruby/opcode.h - RiteVM operation codes
+/**
+** @file mruby/opcode.h - RiteVM operation codes
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/proc.h

-/*
-** mruby/proc.h - Proc class
+/**
+** @file mruby/proc.h - Proc class
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/range.h

-/*
-** mruby/range.h - Range class
+/**
+** @file mruby/range.h - Range class
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/re.h

-/*
-** mruby/re.h - Regexp class
+/**
+** @file mruby/re.h - Regexp class
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/string.h

-/*
-** mruby/string.h - String class
+/**
+** @file mruby/string.h - String class
 **
 ** See Copyright Notice in mruby.h
 */
@@ -90,7 +90,7 @@ struct RString {
 #define RSTR_POOL_P(s) ((s)->flags & MRB_STR_POOL)
 #define RSTR_SET_POOL_FLAG(s) ((s)->flags |= MRB_STR_POOL)
 
-/*
+/**
  * Returns a pointer from a Ruby string
  */
 #define mrb_str_ptr(s)       ((struct RString*)(mrb_ptr(s)))
@@ -121,13 +121,13 @@ MRB_API void mrb_str_modify(mrb_state *mrb, struct RString *s);
 /* mrb_str_modify() with keeping ASCII flag if set */
 MRB_API void mrb_str_modify_keep_ascii(mrb_state *mrb, struct RString *s);
 
-/*
+/**
  * Finds the index of a substring in a string
  */
 MRB_API mrb_int mrb_str_index(mrb_state*, mrb_value, const char*, mrb_int, mrb_int);
 #define mrb_str_index_lit(mrb, str, lit, off) mrb_str_index(mrb, str, lit, mrb_strlen_lit(lit), off);
 
-/*
+/**
  * Appends self to other. Returns self as a concatenated string.
  *
  *
@@ -174,7 +174,7 @@ MRB_API mrb_int mrb_str_index(mrb_state*, mrb_value, const char*, mrb_int, mrb_i
  */
 MRB_API void mrb_str_concat(mrb_state*, mrb_value, mrb_value);
 
-/*
+/**
  * Adds two strings together.
  *
  *
@@ -228,7 +228,7 @@ MRB_API void mrb_str_concat(mrb_state*, mrb_value, mrb_value);
  */
 MRB_API mrb_value mrb_str_plus(mrb_state*, mrb_value, mrb_value);
 
-/*
+/**
  * Converts pointer into a Ruby string.
  *
  * @param [mrb_state] mrb The current mruby state.
@@ -237,7 +237,7 @@ MRB_API mrb_value mrb_str_plus(mrb_state*, mrb_value, mrb_value);
  */
 MRB_API mrb_value mrb_ptr_to_str(mrb_state *, void*);
 
-/*
+/**
  * Returns an object as a Ruby string.
  *
  * @param [mrb_state] mrb The current mruby state.
@@ -246,7 +246,7 @@ MRB_API mrb_value mrb_ptr_to_str(mrb_state *, void*);
  */
 MRB_API mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj);
 
-/*
+/**
  * Resizes the string's length. Returns the amount of characters
  * in the specified by len.
  *
@@ -286,7 +286,7 @@ MRB_API mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj);
  */
 MRB_API mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len);
 
-/*
+/**
  * Returns a sub string.
  *
  *  Example:
@@ -329,7 +329,7 @@ MRB_API mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len);
  */
 MRB_API mrb_value mrb_str_substr(mrb_state *mrb, mrb_value str, mrb_int beg, mrb_int len);
 
-/*
+/**
  * Returns a Ruby string type.
  *
  *
@@ -355,7 +355,7 @@ MRB_API const char *mrb_string_value_ptr(mrb_state *mrb, mrb_value str);
 /* obslete: use RSTRING_LEN() */
 MRB_API mrb_int mrb_string_value_len(mrb_state *mrb, mrb_value str);
 
-/*
+/**
  * Duplicates a string object.
  *
  *
@@ -365,7 +365,7 @@ MRB_API mrb_int mrb_string_value_len(mrb_state *mrb, mrb_value str);
  */
 MRB_API mrb_value mrb_str_dup(mrb_state *mrb, mrb_value str);
 
-/*
+/**
  * Returns a symbol from a passed in Ruby string.
  *
  * @param [mrb_state] mrb The current mruby state.
@@ -379,13 +379,13 @@ MRB_API mrb_value mrb_cstr_to_inum(mrb_state *mrb, const char *s, mrb_int base,
 MRB_API double mrb_str_to_dbl(mrb_state *mrb, mrb_value str, mrb_bool badcheck);
 MRB_API double mrb_cstr_to_dbl(mrb_state *mrb, const char *s, mrb_bool badcheck);
 
-/*
+/**
  * Returns a converted string type.
  * For type checking, non converting `mrb_to_str` is recommended.
  */
 MRB_API mrb_value mrb_str_to_str(mrb_state *mrb, mrb_value str);
 
-/*
+/**
  * Returns true if the strings match and false if the strings don't match.
  *
  * @param [mrb_state] mrb The current mruby state.
@@ -395,8 +395,8 @@ MRB_API mrb_value mrb_str_to_str(mrb_state *mrb, mrb_value str);
  */
 MRB_API mrb_bool mrb_str_equal(mrb_state *mrb, mrb_value str1, mrb_value str2);
 
-/*
- * Returns a concated string comprised of a Ruby string and a C string.
+/**
+ * Returns a concatenated string comprised of a Ruby string and a C string.
  *
  * @param [mrb_state] mrb The current mruby state.
  * @param [mrb_value] str Ruby string.
@@ -407,8 +407,8 @@ MRB_API mrb_bool mrb_str_equal(mrb_state *mrb, mrb_value str1, mrb_value str2);
  */
 MRB_API mrb_value mrb_str_cat(mrb_state *mrb, mrb_value str, const char *ptr, size_t len);
 
-/*
- * Returns a concated string comprised of a Ruby string and a C string.
+/**
+ * Returns a concatenated string comprised of a Ruby string and a C string.
  *
  * @param [mrb_state] mrb The current mruby state.
  * @param [mrb_value] str Ruby string.
@@ -420,17 +420,17 @@ MRB_API mrb_value mrb_str_cat_cstr(mrb_state *mrb, mrb_value str, const char *pt
 MRB_API mrb_value mrb_str_cat_str(mrb_state *mrb, mrb_value str, mrb_value str2);
 #define mrb_str_cat_lit(mrb, str, lit) mrb_str_cat(mrb, str, lit, mrb_strlen_lit(lit))
 
-/*
+/**
  * Adds str2 to the end of str1.
  */
 MRB_API mrb_value mrb_str_append(mrb_state *mrb, mrb_value str, mrb_value str2);
 
-/*
+/**
  * Returns 0 if both Ruby strings are equal. Returns a value < 0 if Ruby str1 is less than Ruby str2. Returns a value > 0 if Ruby str2 is greater than Ruby str1.
  */
 MRB_API int mrb_str_cmp(mrb_state *mrb, mrb_value str1, mrb_value str2);
 
-/*
+/**
  * Returns a newly allocated C string from a Ruby string.
  * This is an utility function to pass a Ruby string to C library functions.
  *
@@ -451,7 +451,7 @@ mrb_value mrb_str_pool(mrb_state *mrb, mrb_value str);
 uint32_t mrb_str_hash(mrb_state *mrb, mrb_value str);
 mrb_value mrb_str_dump(mrb_state *mrb, mrb_value str);
 
-/*
+/**
  * Returns a printable version of str, surrounded by quote marks, with special characters escaped.
  */
 mrb_value mrb_str_inspect(mrb_state *mrb, mrb_value str);

include/mruby/throw.h

-/*
-** mruby/throw.h - mruby exception throwing handler
+/**
+** @file mruby/throw.h - mruby exception throwing handler
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/value.h

-/*
-** mruby/value.h - mruby value definitions
+/**
+** @file mruby/value.h - mruby value definitions
 **
 ** See Copyright Notice in mruby.h
 */
@@ -9,12 +9,27 @@
 
 #include "common.h"
 
-/**
+/*
  * MRuby Value definition functions and macros.
  */
 MRB_BEGIN_DECL
 
+/**
+ * @class mrb_sym
+ * @brief mruby Symbol
+ * 
+ * You can create an mrb_sym by simply using mrb_str_intern() or mrb_intern_cstr()
+ */
 typedef uint32_t mrb_sym;
+
+/**
+ * @class mrb_bool
+ * @brief mruby Boolean
+ *
+ * Used internally to represent boolean. Can be TRUE or FALSE.
+ * Not to be confused with Ruby's boolean classes, which can be 
+ * obtained using mrb_false_value() and mrb_true_value()
+ */
 typedef uint8_t mrb_bool;
 struct mrb_state;
 
@@ -178,8 +193,10 @@ typedef void mrb_value;
 #define mrb_exception_p(o) (mrb_type(o) == MRB_TT_EXCEPTION)
 #define mrb_test(o)   mrb_bool(o)
 
-/*
+/**
  * Returns a float in Ruby.
+ *
+ * Takes a float and boxes it into an mrb_value
  */
 #ifndef MRB_WITHOUT_FLOAT
 MRB_INLINE mrb_value mrb_float_value(struct mrb_state *mrb, mrb_float f)
@@ -200,8 +217,10 @@ mrb_cptr_value(struct mrb_state *mrb, void *p)
   return v;
 }
 
-/*
+/**
  * Returns a fixnum in Ruby.
+ *
+ * Takes an integer and boxes it into an mrb_value
  */
 MRB_INLINE mrb_value mrb_fixnum_value(mrb_int i)
 {
@@ -228,8 +247,7 @@ mrb_obj_value(void *p)
   return v;
 }
 
-
-/*
+/**
  * Get a nil mrb_value object.
  *
  * @return
@@ -242,7 +260,7 @@ MRB_INLINE mrb_value mrb_nil_value(void)
   return v;
 }
 
-/*
+/**
  * Returns false in Ruby.
  */
 MRB_INLINE mrb_value mrb_false_value(void)
@@ -252,7 +270,7 @@ MRB_INLINE mrb_value mrb_false_value(void)
   return v;
 }
 
-/*
+/**
  * Returns true in Ruby.
  */
 MRB_INLINE mrb_value mrb_true_value(void)

include/mruby/variable.h

-/*
-** mruby/variable.h - mruby variables
+/**
+** @file mruby/variable.h - mruby variables
 **
 ** See Copyright Notice in mruby.h
 */

include/mruby/version.h

-/*
-** mruby/version.h - mruby version definition
+/**
+** @file mruby/version.h - mruby version definition
 **
 ** See Copyright Notice in mruby.h
 */