Merge pull request #4669 from davidsiaw/doxygen

Fixes for Doxygen docs

.gitignore

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

Doxyfile

@@ -12,7 +12,7 @@ PROJECT_BRIEF          = "mruby is the lightweight implementation of the Ruby la
 
 PROJECT_LOGO           = doc/mruby_logo_red_icon.png
 
-OUTPUT_DIRECTORY       = doxygen
+OUTPUT_DIRECTORY       = doc/capi
 
 USE_MDFILE_AS_MAINPAGE = README.md
 
@@ -49,6 +49,12 @@ EXTRACT_ALL            = NO
 # Document MRB_INLINE functions
 EXTRACT_STATIC         = YES
 
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = NO
+
+QUIET                  = YES
+WARN_IF_UNDOCUMENTED   = NO
+
 #===========================================================================
 # BELOW THIS LINE IS CRUFT GENERATED BY doxygen -g
 # If you edit anything below this, bring it up here so its easier to read.
@@ -174,22 +180,6 @@ STRIP_FROM_INC_PATH    =
 
 SHORT_NAMES            = NO
 
-# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the
-# first line (until the first dot) of a Javadoc-style comment as the brief
-# description. If set to NO, the Javadoc-style will behave just like regular Qt-
-# style comments (thus requiring an explicit @brief command for a brief
-# description.)
-# The default value is: NO.
-
-JAVADOC_AUTOBRIEF      = NO
-
-# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first
-# line (until the first dot) of a Qt-style comment as the brief description. If
-# set to NO, the Qt-style will behave just like regular Qt-style comments (thus
-# requiring an explicit \brief command for a brief description.)
-# The default value is: NO.
-
-QT_AUTOBRIEF           = NO
 
 # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a
 # multi-line C++ special comment block (i.e. a block of //! or /// comments) as
@@ -711,12 +701,6 @@ CITE_BIB_FILES         =
 # Configuration options related to warning and progress messages
 #---------------------------------------------------------------------------
 
-# The QUIET tag can be used to turn on/off the messages that are generated to
-# standard output by doxygen. If QUIET is set to YES this implies that the
-# messages are off.
-# The default value is: NO.
-
-QUIET                  = NO
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are
 # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
@@ -727,12 +711,6 @@ QUIET                  = NO
 
 WARNINGS               = YES
 
-# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate
-# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag
-# will automatically be disabled.
-# The default value is: YES.
-
-WARN_IF_UNDOCUMENTED   = YES
 
 # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as not documenting some parameters

Makefile

@@ -2,8 +2,6 @@
 # We provide a minimalistic version called minirake inside of our
 # codebase.
 
--include Makefile.doc
-
 RAKE = ruby ./minirake
 
 all :
@@ -14,6 +12,6 @@ test : all
 	$(RAKE) test
 .PHONY : test
 
-clean : docsclean
+clean :
 	$(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 -rf doxygen
-.PHONY : docserver docsclean

README.md

@@ -50,6 +50,19 @@ Or
 
     $ ruby ./minirake test
 
+## Building documentation
+
+There are two sets of documentation in mruby: the mruby API (generated by yard) and C API (Doxygen)
+
+To build both of them, simply go
+
+    rake doc
+
+You can also view them in your browser
+
+    rake view_api
+    rake view_capi
+
 ## How to customize mruby (mrbgems)
 
 mruby contains a package manager called *mrbgems*. To create extensions

Rakefile

@@ -30,6 +30,7 @@ load "#{MRUBY_ROOT}/tasks/libmruby.rake"
 load "#{MRUBY_ROOT}/tasks/benchmark.rake"
 
 load "#{MRUBY_ROOT}/tasks/gitlab.rake"
+load "#{MRUBY_ROOT}/tasks/doc.rake"
 
 def install_D(src, dst)
   opts = { :verbose => $verbose }
@@ -150,19 +151,9 @@ task :clean do
 end
 
 desc "clean everything!"
-task :deep_clean => ["clean"] do
+task :deep_clean => ["clean", "clean_doc"] do
   MRuby.each_target do |t|
     FileUtils.rm_rf t.gem_clone_dir, { :verbose => $verbose }
   end
   puts "Cleaned up mrbgems build folder"
 end
-
-desc 'generate document'
-task :doc do
-  begin
-    sh "mrbdoc"
-  rescue
-    puts "ERROR: To generate documents, you should install yard-mruby gem."
-    puts "  $ gem install yard-mruby"
-  end
-end

include/mruby.h

@@ -177,7 +177,16 @@ struct mrb_context {
 # define MRB_METHOD_CACHE_SIZE (1<<7)
 #endif
 
-typedef mrb_value (*mrb_func_t)(struct mrb_state *mrb, mrb_value);
+/**
+ * Function pointer type for a function callable by mruby.
+ *
+ * The arguments to the function are stored on the mrb_state. To get them see mrb_get_args
+ *
+ * @param mrb The mruby state
+ * @param self The self object
+ * @return [mrb_value] The function's return value
+ */
+typedef mrb_value (*mrb_func_t)(struct mrb_state *mrb, mrb_value self);
 
 #ifdef MRB_METHOD_TABLE_INLINE
 typedef uintptr_t mrb_method_t;
@@ -292,9 +301,9 @@ typedef struct mrb_state {
  *          //free(TheAnimals);
  *      }
  *
- * @param [mrb_state *] mrb The current mruby state.
- * @param [const char *] name The name of the defined class.
- * @param [struct RClass *] super The new class parent.
+ * @param mrb The current mruby state.
+ * @param name The name of the defined class.
+ * @param super The new class parent.
  * @return [struct RClass *] Reference to the newly defined class.
  * @see mrb_define_class_under
  */
@@ -303,12 +312,12 @@ MRB_API struct RClass *mrb_define_class(mrb_state *mrb, const char *name, struct
 /**
  * Defines a new module.
  *
- * @param [mrb_state *] mrb_state* The current mruby state.
- * @param [const char *] char* The name of the module.
+ * @param mrb The current mruby state.
+ * @param name The name of the module.
  * @return [struct RClass *] Reference to the newly defined module.
  */
-MRB_API struct RClass *mrb_define_module(mrb_state *, const char*);
-MRB_API mrb_value mrb_singleton_class(mrb_state*, mrb_value);
+MRB_API struct RClass *mrb_define_module(mrb_state *mrb, const char *name);
+MRB_API mrb_value mrb_singleton_class(mrb_state *mrb, mrb_value val);
 
 /**
  * Include a module in another class or module.
@@ -317,11 +326,11 @@ MRB_API mrb_value mrb_singleton_class(mrb_state*, mrb_value);
  *   module B
  *     include A
  *   end
- * @param [mrb_state *] mrb_state* The current mruby state.
- * @param [struct RClass *] RClass* A reference to module or a class.
- * @param [struct RClass *] RClass* A reference to the module to be included.
+ * @param mrb The current mruby state.
+ * @param cla A reference to module or a class.
+ * @param included A reference to the module to be included.
  */
-MRB_API void mrb_include_module(mrb_state*, struct RClass*, struct RClass*);
+MRB_API void mrb_include_module(mrb_state *mrb, struct RClass *cla, struct RClass *included);
 
 /**
  * Prepends a module in another class or module.
@@ -330,11 +339,11 @@ MRB_API void mrb_include_module(mrb_state*, struct RClass*, struct RClass*);
  *  module B
  *    prepend A
  *  end
- * @param [mrb_state *] mrb_state* The current mruby state.
- * @param [struct RClass *] RClass* A reference to module or a class.
- * @param [struct RClass *] RClass* A reference to the module to be prepended.
+ * @param mrb The current mruby state.
+ * @param cla A reference to module or a class.
+ * @param prepended A reference to the module to be prepended.
  */
-MRB_API void mrb_prepend_module(mrb_state*, struct RClass*, struct RClass*);
+MRB_API void mrb_prepend_module(mrb_state *mrb, struct RClass *cla, struct RClass *prepended);
 
 /**
  * Defines a global function in ruby.
@@ -343,7 +352,6 @@ MRB_API void mrb_prepend_module(mrb_state*, struct RClass*, struct RClass*);
  *
  * Example:
  *
- *     !!!c
  *     mrb_value example_method(mrb_state* mrb, mrb_value self)
  *     {
  *          puts("Executing example command!");
@@ -355,11 +363,11 @@ MRB_API void mrb_prepend_module(mrb_state*, struct RClass*, struct RClass*);
  *           mrb_define_method(mrb, mrb->kernel_module, "example_method", example_method, MRB_ARGS_NONE());
  *     }
  *
- * @param [mrb_state *] mrb The MRuby state reference.
- * @param [struct RClass *] cla The class pointer where the method will be defined.
- * @param [const char *] name The name of the method being defined.
- * @param [mrb_func_t] func The function pointer to the method definition.
- * @param [mrb_aspec] aspec The method parameters declaration.
+ * @param mrb The MRuby state reference.
+ * @param cla The class pointer where the method will be defined.
+ * @param name The name of the method being defined.
+ * @param func The function pointer to the method definition.
+ * @param aspec The method parameters declaration.
  */
 MRB_API void mrb_define_method(mrb_state *mrb, struct RClass *cla, const char *name, mrb_func_t func, mrb_aspec aspec);
 
@@ -382,14 +390,20 @@ MRB_API void mrb_define_method(mrb_state *mrb, struct RClass *cla, const char *n
  *       foo = mrb_define_class(mrb, "Foo", mrb->object_class);
  *       mrb_define_class_method(mrb, foo, "bar", bar_method, MRB_ARGS_NONE());
  *     }
- * @param [mrb_state *] mrb_state* The MRuby state reference.
- * @param [struct RClass *] RClass* The class where the class method will be defined.
- * @param [const char *] char* The name of the class method being defined.
- * @param [mrb_func_t] mrb_func_t The function pointer to the class method definition.
- * @param [mrb_aspec] mrb_aspec The method parameters declaration.
+ * @param mrb The MRuby state reference.
+ * @param cla The class where the class method will be defined.
+ * @param name The name of the class method being defined.
+ * @param fun The function pointer to the class method definition.
+ * @param aspec The method parameters declaration.
+ */
+MRB_API void mrb_define_class_method(mrb_state *mrb, struct RClass *cla, const char *name, mrb_func_t fun, mrb_aspec aspec);
+
+/**
+ * Defines a singleton method
+ *
+ * @see mrb_define_class_method
  */
-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_singleton_method(mrb_state *mrb, struct RObject *cla, const char *name, mrb_func_t fun, mrb_aspec aspec);
 
 /**
  *  Defines a module function.
@@ -410,13 +424,13 @@ MRB_API void mrb_define_singleton_method(mrb_state*, struct RObject*, const char
  *          foo = mrb_define_module(mrb, "Foo");
  *          mrb_define_module_function(mrb, foo, "bar", bar_method, MRB_ARGS_NONE());
  *        }
- *  @param [mrb_state *] mrb_state* The MRuby state reference.
- *  @param [struct RClass *] RClass* The module where the module function will be defined.
- *  @param [const char *] char* The name of the module function being defined.
- *  @param [mrb_func_t] mrb_func_t The function pointer to the module function definition.
- *  @param [mrb_aspec] mrb_aspec The method parameters declaration.
+ *  @param mrb The MRuby state reference.
+ *  @param cla The module where the module function will be defined.
+ *  @param name The name of the module function being defined.
+ *  @param fun The function pointer to the module function definition.
+ *  @param aspec The method parameters declaration.
  */
-MRB_API void mrb_define_module_function(mrb_state*, struct RClass*, const char*, mrb_func_t, mrb_aspec);
+MRB_API void mrb_define_module_function(mrb_state *mrb, struct RClass *cla, const char *name, mrb_func_t fun, mrb_aspec aspec);
 
 /**
  *  Defines a constant.
@@ -439,12 +453,12 @@ MRB_API void mrb_define_module_function(mrb_state*, struct RClass*, const char*,
  *          mrb_value
  *          mrb_example_gem_final(mrb_state* mrb){
  *          }
- *  @param [mrb_state *] mrb_state* The MRuby state reference.
- *  @param [struct RClass *] RClass* A class or module the constant is defined in.
- *  @param [const char *] name The name of the constant being defined.
- *  @param [mrb_value] mrb_value The value for the constant.
+ *  @param mrb The MRuby state reference.
+ *  @param cla A class or module the constant is defined in.
+ *  @param name The name of the constant being defined.
+ *  @param val The value for the constant.
  */
-MRB_API void mrb_define_const(mrb_state*, struct RClass*, const char *name, mrb_value);
+MRB_API void mrb_define_const(mrb_state* mrb, struct RClass* cla, const char *name, mrb_value val);
 
 /**
  * Undefines a method.
@@ -490,11 +504,11 @@ MRB_API void mrb_define_const(mrb_state*, struct RClass*, const char *name, mrb_
  *
  *     mrb_example_gem_final(mrb_state* mrb){
  *     }
- * @param [mrb_state*] mrb_state* The mruby state reference.
- * @param [struct RClass*] RClass* A class the method will be undefined from.
- * @param [const char*] const char* The name of the method to be undefined.
+ * @param mrb The mruby state reference.
+ * @param cla The class the method will be undefined from.
+ * @param name The name of the method to be undefined.
  */
-MRB_API void mrb_undef_method(mrb_state*, struct RClass*, const char*);
+MRB_API void mrb_undef_method(mrb_state *mrb, struct RClass *cla, const char *name);
 MRB_API void mrb_undef_method_id(mrb_state*, struct RClass*, mrb_sym);
 
 /**
@@ -530,11 +544,11 @@ MRB_API void mrb_undef_method_id(mrb_state*, struct RClass*, mrb_sym);
  *      void
  *      mrb_example_gem_final(mrb_state* mrb){
  *      }
- * @param [mrb_state*] mrb_state* The mruby state reference.
- * @param [RClass*] RClass* A class the class method will be undefined from.
- * @param [const char*] const char* The name of the class method to be undefined.
+ * @param mrb The mruby state reference.
+ * @param cls A class the class method will be undefined from.
+ * @param name The name of the class method to be undefined.
  */
-MRB_API void mrb_undef_class_method(mrb_state*, struct RClass*, const char*);
+MRB_API void mrb_undef_class_method(mrb_state *mrb, struct RClass *cls, const char *name);
 
 /**
  * Initialize a new object instance of c class.
@@ -558,10 +572,10 @@ MRB_API void mrb_undef_class_method(mrb_state*, struct RClass*, const char*);
  *       obj = mrb_obj_new(mrb, example_class, 0, NULL); # => ExampleClass.new
  *       mrb_p(mrb, obj); // => Kernel#p
  *      }
- * @param [mrb_state*] mrb The current mruby state.
- * @param [RClass*] c Reference to the class of the new object.
- * @param [mrb_int] argc Number of arguments in argv
- * @param [const mrb_value *] argv Array of mrb_value to initialize the object
+ * @param mrb The current mruby state.
+ * @param c Reference to the class of the new object.
+ * @param argc Number of arguments in argv
+ * @param argv Array of mrb_value to initialize the object
  * @return [mrb_value] The newly initialized object
  */
 MRB_API mrb_value mrb_obj_new(mrb_state *mrb, struct RClass *c, mrb_int argc, const mrb_value *argv);
@@ -587,8 +601,8 @@ MRB_INLINE mrb_value mrb_class_new_instance(mrb_state *mrb, mrb_int argc, const
  *        mrb_p(mrb, obj); // => Kernel#p
  *       }
  *
- * @param [mrb_state*] mrb The current mruby state.
- * @param [struct RClass *] super The super class or parent.
+ * @param mrb The current mruby state.
+ * @param super The super class or parent.
  * @return [struct RClass *] Reference to the new class.
  */
 MRB_API struct RClass * mrb_class_new(mrb_state *mrb, struct RClass *super);
@@ -604,7 +618,7 @@ MRB_API struct RClass * mrb_class_new(mrb_state *mrb, struct RClass *super);
  *        example_module = mrb_module_new(mrb);
  *      }
  *
- * @param [mrb_state*] mrb The current mruby state.
+ * @param mrb The current mruby state.
  * @return [struct RClass *] Reference to the new module.
  */
 MRB_API struct RClass * mrb_module_new(mrb_state *mrb);
@@ -631,24 +645,24 @@ MRB_API struct RClass * mrb_module_new(mrb_state *mrb);
  *       }
  *      }
  *
- * @param [mrb_state*] mrb The current mruby state.
- * @param [const char *] name A string representing the name of the class.
+ * @param mrb The current mruby state.
+ * @param name A string representing the name of the class.
  * @return [mrb_bool] A boolean value.
  */
 MRB_API mrb_bool mrb_class_defined(mrb_state *mrb, const char *name);
 
 /**
  * Gets a class.
- * @param [mrb_state*] mrb The current mruby state.
- * @param [const char *] name The name of the class.
+ * @param mrb The current mruby state.
+ * @param name The name of the class.
  * @return [struct RClass *] A reference to the class.
 */
 MRB_API struct RClass * mrb_class_get(mrb_state *mrb, const char *name);
 
 /**
  * Gets a exception class.
- * @param [mrb_state*] mrb The current mruby state.
- * @param [const char *] name The name of the class.
+ * @param mrb The current mruby state.
+ * @param name The name of the class.
  * @return [struct RClass *] A reference to the class.
 */
 MRB_API struct RClass * mrb_exc_get(mrb_state *mrb, const char *name);
@@ -677,35 +691,35 @@ MRB_API struct RClass * mrb_exc_get(mrb_state *mrb, const char *name);
  *       }
  *      }
  *
- * @param [mrb_state*] mrb The current mruby state.
- * @param [struct RClass *] outer The name of the outer class.
- * @param [const char *] name A string representing the name of the inner class.
+ * @param mrb The current mruby state.
+ * @param outer The name of the outer class.
+ * @param name A string representing the name of the inner class.
  * @return [mrb_bool] A boolean value.
  */
 MRB_API mrb_bool mrb_class_defined_under(mrb_state *mrb, struct RClass *outer, const char *name);
 
 /**
  * Gets a child class.
- * @param [mrb_state*] mrb The current mruby state.
- * @param [struct RClass *] outer The name of the parent class.
- * @param [const char *] name The name of the class.
+ * @param mrb The current mruby state.
+ * @param outer The name of the parent class.
+ * @param name The name of the class.
  * @return [struct RClass *] A reference to the class.
 */
 MRB_API struct RClass * mrb_class_get_under(mrb_state *mrb, struct RClass *outer, const char *name);
 
 /**
  * Gets a module.
- * @param [mrb_state*] mrb The current mruby state.
- * @param [const char *] name The name of the module.
+ * @param mrb The current mruby state.
+ * @param name The name of the module.
  * @return [struct RClass *] A reference to the module.
 */
 MRB_API struct RClass * mrb_module_get(mrb_state *mrb, const char *name);
 
 /**
  * Gets a module defined under another module.
- * @param [mrb_state*] mrb The current mruby state.
- * @param [struct RClass *] outer The name of the outer module.
- * @param [const char *] name The name of the module.
+ * @param mrb The current mruby state.
+ * @param outer The name of the outer module.
+ * @param name The name of the module.
  * @return [struct RClass *] A reference to the module.
 */
 MRB_API struct RClass * mrb_module_get_under(mrb_state *mrb, struct RClass *outer, const char *name);
@@ -719,8 +733,8 @@ MRB_API mrb_value mrb_notimplement_m(mrb_state*, mrb_value);
  *
  * Equivalent to:
  *   Object#dup
- * @param [mrb_state*] mrb The current mruby state.
- * @param [mrb_value] obj Object to be duplicate.
+ * @param mrb The current mruby state.
+ * @param obj Object to be duplicate.
  * @return [mrb_value] The newly duplicated object.
  */
 MRB_API mrb_value mrb_obj_dup(mrb_state *mrb, mrb_value obj);
@@ -760,9 +774,9 @@ MRB_API mrb_value mrb_obj_dup(mrb_state *mrb, mrb_value obj);
  *        }
  *      }
  *
- * @param [mrb_state*] mrb The current mruby state.
- * @param [struct RClass *] c A reference to a class.
- * @param [mrb_sym] mid A symbol referencing a method id.
+ * @param mrb The current mruby state.
+ * @param c A reference to a class.
+ * @param mid A symbol referencing a method id.
  * @return [mrb_bool] A boolean value.
  */
 MRB_API mrb_bool mrb_obj_respond_to(mrb_state *mrb, struct RClass* c, mrb_sym mid);
@@ -770,10 +784,10 @@ MRB_API mrb_bool mrb_obj_respond_to(mrb_state *mrb, struct RClass* c, mrb_sym mi
 /**
  * Defines a new class under a given module
  *
- * @param [mrb_state*] mrb The current mruby state.
- * @param [struct RClass *] outer Reference to the module under which the new class will be defined
- * @param [const char *] name The name of the defined class
- * @param [struct RClass *] super The new class parent
+ * @param mrb The current mruby state.
+ * @param outer Reference to the module under which the new class will be defined
+ * @param name The name of the defined class
+ * @param super The new class parent
  * @return [struct RClass *] Reference to the newly defined class
  * @see mrb_define_class
  */
@@ -854,7 +868,7 @@ MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *o
  * | `I`  | inline struct  | void *          |                                                    |
  * | `&`  | block          | {mrb_value}       | &! raises exception if no block given.             |
  * | `*`  | rest arguments | {mrb_value} *, {mrb_int} | Receive the rest of arguments as an array; `*!` avoid copy of the stack.  |
- * | &vert; | optional     |                   | After this spec following specs would be optional. |
+ * | <code>\|</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. |
  *
  * @see mrb_get_args
@@ -865,7 +879,7 @@ typedef const char *mrb_args_format;
  * Retrieve arguments from mrb_state.
  *
  * @param mrb The current MRuby state.
- * @param format [mrb_args_format] is a list of format specifiers
+ * @param 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
@@ -898,6 +912,8 @@ MRB_API mrb_value* mrb_get_argv(mrb_state *mrb);
 /**
  * Call existing ruby functions.
  *
+ * Example:
+ *
  *      #include <stdio.h>
  *      #include <mruby.h>
  *      #include "mruby/compile.h"
@@ -915,14 +931,15 @@ MRB_API mrb_value* mrb_get_argv(mrb_state *mrb);
  *        fclose(fp);
  *        mrb_close(mrb);
  *      }
- * @param [mrb_state*] mrb_state* The current mruby state.
- * @param [mrb_value] mrb_value A reference to an mruby value.
- * @param [const char*] const char* The name of the method.
- * @param [mrb_int] mrb_int The number of arguments the method has.
- * @param [...] ... Variadic values(not type safe!).
- * @return [mrb_value] mrb_value mruby function value.
+ *
+ * @param mrb The current mruby state.
+ * @param val A reference to an mruby value.
+ * @param name The name of the method.
+ * @param argc The number of arguments the method has.
+ * @param ... Variadic values(not type safe!).
+ * @return [mrb_value] mruby function value.
  */
-MRB_API mrb_value mrb_funcall(mrb_state*, mrb_value, const char*, mrb_int,...);
+MRB_API mrb_value mrb_funcall(mrb_state *mrb, mrb_value val, const char *name, mrb_int argc, ...);
 /**
  * Call existing ruby functions. This is basically the type safe version of mrb_funcall.
  *
@@ -944,15 +961,15 @@ MRB_API mrb_value mrb_funcall(mrb_state*, mrb_value, const char*, mrb_int,...);
  *        fclose(fp);
  *        mrb_close(mrb);
  *       }
- * @param [mrb_state*] mrb_state* The current mruby state.
- * @param [mrb_value] mrb_value A reference to an mruby value.
- * @param [mrb_sym] mrb_sym The symbol representing the method.
- * @param [mrb_int] mrb_int The number of arguments the method has.
- * @param [const mrb_value*] mrb_value* Pointer to the object.
+ * @param mrb The current mruby state.
+ * @param val A reference to an mruby value.
+ * @param name_sym The symbol representing the method.
+ * @param argc The number of arguments the method has.
+ * @param obj Pointer to the object.
  * @return [mrb_value] mrb_value mruby function value.
  * @see mrb_funcall
  */
-MRB_API mrb_value mrb_funcall_argv(mrb_state*, mrb_value, mrb_sym, mrb_int, const mrb_value*);
+MRB_API mrb_value mrb_funcall_argv(mrb_state *mrb, mrb_value val, mrb_sym name_sym, mrb_int argc, const mrb_value* obj);
 /**
  * Call existing ruby functions with a block.
  */
@@ -960,16 +977,19 @@ MRB_API mrb_value mrb_funcall_with_block(mrb_state*, mrb_value, mrb_sym, mrb_int
 /**
  * Create a symbol
  *
+ * Example:
+ *
  *     # Ruby style:
  *     :pizza # => :pizza
  *
  *     // C style:
  *     mrb_sym m_sym = mrb_intern_lit(mrb, "pizza"); //  => :pizza
- * @param [mrb_state*] mrb_state* The current mruby state.
- * @param [const char*] const char* The name of the method.
+ *
+ * @param mrb The current mruby state.
+ * @param str The string to be symbolized
  * @return [mrb_sym] mrb_sym A symbol.
  */
-MRB_API mrb_sym mrb_intern_cstr(mrb_state*,const char*);
+MRB_API mrb_sym mrb_intern_cstr(mrb_state *mrb, const char* str);
 MRB_API mrb_sym mrb_intern(mrb_state*,const char*,size_t);
 MRB_API mrb_sym mrb_intern_static(mrb_state*,const char*,size_t);
 #define mrb_intern_lit(mrb, lit) mrb_intern_static(mrb, lit, mrb_strlen_lit(lit))
@@ -1220,31 +1240,31 @@ MRB_API mrb_bool mrb_obj_is_instance_of(mrb_state *mrb, mrb_value obj, struct RC
 MRB_API mrb_bool mrb_func_basic_p(mrb_state *mrb, mrb_value obj, mrb_sym mid, mrb_func_t func);
 
 
-/*
+/**
  * Resume a Fiber
  *
- * @mrbgem mruby-fiber
+ * Implemented in 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
+ * Implemented in mruby-fiber
  */
 MRB_API mrb_value mrb_fiber_yield(mrb_state *mrb, mrb_int argc, const mrb_value *argv);
 
-/*
+/**
  * Check if a Fiber is alive
  *
- * @mrbgem mruby-fiber
+ * Implemented in mruby-fiber
  */
 MRB_API mrb_value mrb_fiber_alive_p(mrb_state *mrb, mrb_value fib);
 
-/*
+/**
  * FiberError reference
  *
- * @mrbgem mruby-fiber
+ * Implemented in mruby-fiber
  */
 #define E_FIBER_ERROR (mrb_exc_get(mrb, "FiberError"))
 MRB_API void mrb_stack_extend(mrb_state*, mrb_int);

include/mruby/error.h

@@ -69,14 +69,14 @@ mrb_break_value_set(struct RBreak *brk, mrb_value val)
 /**
  * Protect
  *
- * @mrbgem mruby-error
+ * Implemented in the mruby-error mrbgem
  */
 MRB_API mrb_value mrb_protect(mrb_state *mrb, mrb_func_t body, mrb_value data, mrb_bool *state);
 
 /**
  * Ensure
  *
- * @mrbgem mruby-error
+ * Implemented in the mruby-error mrbgem
  */
 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);
@@ -84,7 +84,7 @@ MRB_API mrb_value mrb_ensure(mrb_state *mrb, mrb_func_t body, mrb_value b_data,
 /**
  * Rescue
  *
- * @mrbgem mruby-error
+ * Implemented in the mruby-error mrbgem
  */
 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);
@@ -92,7 +92,7 @@ MRB_API mrb_value mrb_rescue(mrb_state *mrb, mrb_func_t body, mrb_value b_data,
 /**
  * Rescue exception
  *
- * @mrbgem mruby-error
+ * Implemented in the mruby-error mrbgem
  */
 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,

include/mruby/string.h

@@ -138,7 +138,6 @@ MRB_API mrb_int mrb_str_index(mrb_state*, mrb_value, const char*, mrb_int, mrb_i
  *
  * Example:
  *
- *     !!!c
  *     int
  *     main(int argc,
  *          char **argv)
@@ -167,17 +166,16 @@ MRB_API mrb_int mrb_str_index(mrb_state*, mrb_value, const char*, mrb_int, mrb_i
  *       return 0;
  *     } 
  *
- *
  * Result:
  *
  *     => "abcdef"
  *
- * @param [mrb_state] mrb The current mruby state.
- * @param [mrb_value] self String to concatenate.
- * @param [mrb_value] other String to append to self.
+ * @param mrb The current mruby state.
+ * @param self String to concatenate.
+ * @param other String to append to self.
  * @return [mrb_value] Returns a new String appending other to self.
  */
-MRB_API void mrb_str_concat(mrb_state*, mrb_value, mrb_value);
+MRB_API void mrb_str_concat(mrb_state *mrb, mrb_value self, mrb_value other);
 
 /**
  * Adds two strings together.
@@ -185,7 +183,6 @@ MRB_API void mrb_str_concat(mrb_state*, mrb_value, mrb_value);
  *
  * Example:
  *
- *     !!!c
  *     int
  *     main(int argc,
  *          char **argv)
@@ -226,27 +223,27 @@ MRB_API void mrb_str_concat(mrb_state*, mrb_value, mrb_value);
  *     => "def"  # Second string
  *     => "abcdef" # First & Second concatenated.
  *
- * @param [mrb_state] mrb The current mruby state.
- * @param [mrb_value] a First string to concatenate.
- * @param [mrb_value] b Second string to concatenate.
+ * @param mrb The current mruby state.
+ * @param a First string to concatenate.
+ * @param b Second string to concatenate.
  * @return [mrb_value] Returns a new String containing a concatenated to b.
  */
-MRB_API mrb_value mrb_str_plus(mrb_state*, mrb_value, mrb_value);
+MRB_API mrb_value mrb_str_plus(mrb_state *mrb, mrb_value a, mrb_value b);
 
 /**
  * Converts pointer into a Ruby string.
  *
- * @param [mrb_state] mrb The current mruby state.
- * @param [void*] p The pointer to convert to Ruby string.
+ * @param mrb The current mruby state.
+ * @param p The pointer to convert to Ruby string.
  * @return [mrb_value] Returns a new Ruby String.
  */
-MRB_API mrb_value mrb_ptr_to_str(mrb_state *, void*);
+MRB_API mrb_value mrb_ptr_to_str(mrb_state *mrb, void *p);
 
 /**
  * Returns an object as a Ruby string.
  *
- * @param [mrb_state] mrb The current mruby state.
- * @param [mrb_value] obj An object to return as a Ruby string.
+ * @param mrb The current mruby state.
+ * @param obj An object to return as a Ruby string.
  * @return [mrb_value] An object as a Ruby string.
  */
 MRB_API mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj);
@@ -257,7 +254,6 @@ MRB_API mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj);
  *
  * Example:
  *
- *     !!!c
  *     int
  *     main(int argc,
  *          char **argv)
@@ -284,9 +280,9 @@ MRB_API mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj);
  *
  *      => "Hello"
  *
- * @param [mrb_state] mrb The current mruby state.
- * @param [mrb_value] str The Ruby string to resize.
- * @param [mrb_value] len The length.
+ * @param mrb The current mruby state.
+ * @param str The Ruby string to resize.
+ * @param len The length.
  * @return [mrb_value] An object as a Ruby string.
  */
 MRB_API mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len);
@@ -296,7 +292,6 @@ MRB_API mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len);
  *
  * Example:
  *
- *     !!!c
  *     int
  *     main(int argc,
  *     char const **argv)
@@ -326,10 +321,10 @@ MRB_API mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len);
  *
  *     => "He"
  *
- * @param [mrb_state] mrb The current mruby state.
- * @param [mrb_value] str Ruby string.
- * @param [mrb_int] beg The beginning point of the sub-string.
- * @param [mrb_int] len The end point of the sub-string.
+ * @param mrb The current mruby state.
+ * @param str Ruby string.
+ * @param beg The beginning point of the sub-string.
+ * @param len The end point of the sub-string.
  * @return [mrb_value] An object as a Ruby sub-string.
  */
 MRB_API mrb_value mrb_str_substr(mrb_state *mrb, mrb_value str, mrb_int beg, mrb_int len);
@@ -338,8 +333,8 @@ MRB_API mrb_value mrb_str_substr(mrb_state *mrb, mrb_value str, mrb_int beg, mrb
  * Returns a Ruby string type.
  *
  *
- * @param [mrb_state] mrb The current mruby state.
- * @param [mrb_value] str Ruby string.
+ * @param mrb The current mruby state.
+ * @param str Ruby string.
  * @return [mrb_value] A Ruby string.
  */
 MRB_API mrb_value mrb_ensure_string_type(mrb_state *mrb, mrb_value str);
@@ -364,8 +359,8 @@ MRB_API mrb_int mrb_string_value_len(mrb_state *mrb, mrb_value str);
  * Duplicates a string object.
  *
  *
- * @param [mrb_state] mrb The current mruby state.
- * @param [mrb_value] str Ruby string.
+ * @param mrb The current mruby state.
+ * @param str Ruby string.
  * @return [mrb_value] Duplicated Ruby string.
  */
 MRB_API mrb_value mrb_str_dup(mrb_state *mrb, mrb_value str);
@@ -373,8 +368,8 @@ 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.
- * @param [mrb_value] self Ruby string.
+ * @param mrb The current mruby state.
+ * @param self Ruby string.
  * @return [mrb_value] A symbol.
  */
 MRB_API mrb_value mrb_str_intern(mrb_state *mrb, mrb_value self);
@@ -393,9 +388,9 @@ 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.
- * @param [mrb_value] str1 Ruby string to compare.
- * @param [mrb_value] str2 Ruby string to compare.
+ * @param mrb The current mruby state.
+ * @param str1 Ruby string to compare.
+ * @param str2 Ruby string to compare.
  * @return [mrb_value] boolean value.
  */
 MRB_API mrb_bool mrb_str_equal(mrb_state *mrb, mrb_value str1, mrb_value str2);
@@ -403,10 +398,10 @@ MRB_API mrb_bool mrb_str_equal(mrb_state *mrb, mrb_value str1, mrb_value str2);
 /**
  * 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.
- * @param [const char *] ptr A C string.
- * @param [size_t] len length of C string.
+ * @param mrb The current mruby state.
+ * @param str Ruby string.
+ * @param ptr A C string.
+ * @param len length of C string.
  * @return [mrb_value] A Ruby string.
  * @see mrb_str_cat_cstr
  */
@@ -415,9 +410,9 @@ MRB_API mrb_value mrb_str_cat(mrb_state *mrb, mrb_value str, const char *ptr, si
 /**
  * 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.
- * @param [const char *] ptr A C string.
+ * @param mrb The current mruby state.
+ * @param str Ruby string.
+ * @param ptr A C string.
  * @return [mrb_value] A Ruby string.
  * @see mrb_str_cat
  */
@@ -446,8 +441,8 @@ MRB_API int mrb_str_cmp(mrb_state *mrb, mrb_value str1, mrb_value str2);
  * - Caller can modify returned string without affecting Ruby string
  *   (e.g. it can be used for mkstemp(3)).
  *
- * @param [mrb_state *] mrb The current mruby state.
- * @param [mrb_value] str Ruby string. Must be an instance of String.
+ * @param mrb The current mruby state.
+ * @param str Ruby string. Must be an instance of String.
  * @return [char *] A newly allocated C string.
  */
 MRB_API char *mrb_str_to_cstr(mrb_state *mrb, mrb_value str);

include/mruby/value.h

@@ -15,16 +15,17 @@
 MRB_BEGIN_DECL
 
 /**
+ * mruby Symbol.
  * @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;
 
 /**
+ * mruby Boolean.
  * @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 

include/mruby/variable.h

@@ -97,18 +97,15 @@ MRB_API void mrb_gv_set(mrb_state *mrb, mrb_sym sym, mrb_value val);
  *
  * Example:
  *
- *     !!!ruby
  *     # Ruby style
  *     $value = nil
  *
- *     !!!c
  *     // C style
  *     mrb_sym sym = mrb_intern_lit(mrb, "$value");
  *     mrb_gv_remove(mrb, sym);
  *
  * @param mrb The mruby state reference
  * @param sym The name of the global variable
- * @param val The value of the global variable
  */
 MRB_API void mrb_gv_remove(mrb_state *mrb, mrb_sym sym);
 

src/class.c

@@ -409,7 +409,7 @@ mrb_module_get(mrb_state *mrb, const char *name)
 /*!
  * Defines a class under the namespace of \a outer.
  * \param outer  a class which contains the new class.
- * \param id     name of the new class
+ * \param name     name of the new class
  * \param super  a class from which the new class will derive.
  *               NULL means \c Object class.
  * \return the created class
@@ -1769,6 +1769,7 @@ mrb_alias_method(mrb_state *mrb, struct RClass *c, mrb_sym a, mrb_sym b)
 
 /*!
  * Defines an alias of a method.
+ * \param mrb    the mruby state
  * \param klass  the class which the original method belongs to
  * \param name1  a new name for the method
  * \param name2  the original name of the method

tasks/doc.rake

+desc 'generate document'
+task :doc => [:api_doc, :capi_doc] do
+
+end
+
+desc 'generate yard docs'
+task :api_doc do
+  begin
+    sh "mrbdoc"
+  rescue
+    puts "ERROR: To generate yard documentation, you should install yard-mruby gem."
+    puts "  $ gem install yard-mruby yard-coderay"
+  end
+end
+
+desc 'generate doxygen docs'
+task :capi_doc do
+  begin
+    sh "doxygen Doxyfile"
+  rescue
+    puts "ERROR: To generate C API documents, you need Doxygen."
+    puts "  $ sudo apt-get install doxygen"
+  end
+end
+
+desc 'clean all built docs'
+task :clean_api_doc do
+  FileUtils.rm_rf 'doc/api'
+end
+
+desc 'clean all built docs'
+task :clean_capi_doc do
+  FileUtils.rm_rf 'doc/capi'
+end
+
+desc 'clean all built docs'
+task :clean_doc => [:clean_api_doc, :clean_capi_doc] do
+end
+
+desc 'clean all built docs'
+task :view_api => [:api_doc] do
+  sh 'xdg-open doc/api/index.html'
+end
+
+desc 'clean all built docs'
+task :view_capi => [:capi_doc] do
+  sh 'xdg-open doc/capi/html/index.html'
+end