Added YARD docs in new mruby.h

1 files changed, 226 insertions, 205 deletions

diff --git a/include/mruby.h b/include/mruby.h
index 9d482f35e..2f4ddac02 100644
--- a/include/mruby.h
+++ b/include/mruby.h
@@ -263,28 +263,22 @@ MRB_API void mrb_define_method(mrb_state *mrb, struct RClass *cla, const char *n
  * Defines a class method.
  *
  * Example:
- *   # Ruby style
- *   class Foo
  *
- *     def Foo.bar
+ *     # Ruby style
+ *     class Foo
+ *      def Foo.bar
+ *      end
  *     end
  *
- *   end
- *   // C style
- *   mrb_value bar_method(mrb_state* mrb, mrb_value self){
- *
- *     return mrb_nil_value();
- *
- *   }
- *   void mrb_example_gem_init(mrb_state* mrb){
- *
- *     struct RClass *foo;
- *
- *     foo = mrb_define_class(mrb, "Foo", mrb->object_class);
- *
- *     mrb_define_class_method(mrb, foo, "bar", bar_method, MRB_ARGS_NONE());
- * 
- *   }
+ *     // C style
+ *     mrb_value bar_method(mrb_state* mrb, mrb_value self){
+ *       return mrb_nil_value();
+ *     }
+ *     void mrb_example_gem_init(mrb_state* mrb){
+ *       struct RClass *foo;
+ *       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.
@@ -298,26 +292,21 @@ MRB_API void mrb_define_singleton_method(mrb_state*, struct RObject*, const char
  *  Defines a module fuction.
  *
  * Example:
- *   # Ruby style
- *   module Foo
- *                                                                                                     
- *     def Foo.bar                                                                                                    *     end
- *
- *   end                                                                                                             
- *   // C style                                                                                                      
- *   mrb_value bar_method(mrb_state* mrb, mrb_value self){ 
- *                                                          
- *     return mrb_nil_value();                                                                                        *               
- *   }                                                                                                               
- *   void mrb_example_gem_init(mrb_state* mrb){
- *                                                                      
- *     struct RClass *foo;
- *                                                                                           
- *     foo = mrb_define_module(mrb, "Foo");
- *                                                        
- *     mrb_define_module_function(mrb, foo, "bar", bar_method, MRB_ARGS_NONE());
- *
- *   }    
+ *
+ *        # Ruby style
+ *        module Foo                                                                                                  
+ *          def Foo.bar
+ *          end                                                                                                 
+ *        end                                                                                                             
+ *        // C style                                                                                                      
+ *        mrb_value bar_method(mrb_state* mrb, mrb_value self){                                                          
+ *          return mrb_nil_value();                                                                                                     
+ *        }                                                                                                               
+ *        void mrb_example_gem_init(mrb_state* mrb){                                                                     
+ *          struct RClass *foo;                                                                                           
+ *          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.
@@ -330,29 +319,24 @@ MRB_API void mrb_define_module_function(mrb_state*, struct RClass*, const char*,
  *  Defines a constant.
  *
  * Example:
- *    # Ruby style
- *
- *    class ExampleClass
- *    
- *    AGE = 22
- *
- *    end
- *
- *    // C style
- *    #include <stdio.h> 
- *    #include <mruby.h>
  *
- *    void
- *    mrb_example_gem_init(mrb_state* mrb){
- * 
- *      mrb_define_const(mrb, mrb->kernel_module, "AGE", mrb_fixnum_value(22));
+ *          # Ruby style
  *
- *    }
+ *          class ExampleClass
+ *            AGE = 22
+ *          end
  *
- *    mrb_value
- *    mrb_example_gem_final(mrb_state* mrb){
+ *          // C style
+ *          #include <stdio.h> 
+ *          #include <mruby.h>
+ *          void
+ *          mrb_example_gem_init(mrb_state* mrb){
+ *            mrb_define_const(mrb, mrb->kernel_module, "AGE", mrb_fixnum_value(22));
+ *          }
  *
- *    }
+ *          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.
@@ -364,59 +348,44 @@ MRB_API void mrb_define_const(mrb_state*, struct RClass*, const char *name, mrb_
  * Undefines a method.
  *
  * Example:
- *   # Ruby style
  *
- *   class ExampleClassA
+ *     # Ruby style
  *
- *     def example_method
- *       "example"
+ *     class ExampleClassA
+ *       def example_method
+ *         "example"
+ *       end
  *     end
+ *     ExampleClassA.new.example_method # => example
  *
- *   end
- *
- *   ExampleClassA.new.example_method # => example
- *
- *   class ExampleClassB < ExampleClassA
- *
- *     undef_method :example_method
- *
- *   end
+ *     class ExampleClassB < ExampleClassA
+ *       undef_method :example_method
+ *     end
  *
- *   ExampleClassB.new.example_method # => undefined method 'example_method' for ExampleClassB (NoMethodError)
+ *     ExampleClassB.new.example_method # => undefined method 'example_method' for ExampleClassB (NoMethodError)
  *
- *   // C style
- *   #include <stdio.h>
- *   #include <mruby.h>
+ *     // C style
+ *     #include <stdio.h>
+ *     #include <mruby.h>
  *  
- *   mrb_value
- *   mrb_example_method(mrb_state *mrb){
- *
- *     return mrb_str_new_cstr(mrb, "example");
- *
- *   }
- *
- *   void
- *   mrb_example_gem_init(mrb_state* mrb){
- *     struct RClass *example_class_a;
- *     struct RClass *example_class_b;
- *     struct RClass *example_class_c;
- *
- *     example_class_a = mrb_define_class(mrb, "ExampleClassA", mrb->object_class);
- *
- *     mrb_define_method(mrb, example_class_a, "example_method", mrb_example_method, MRB_ARGS_NONE());
- *
- *     example_class_b = mrb_define_class(mrb, "ExampleClassB", example_class_a);
- *
- *     example_class_c = mrb_define_class(mrb, "ExampleClassC", example_class_b);
- *
- *     mrb_undef_method(mrb, example_class_c, "example_method");
- *
- *   }
- *
- *   mrb_example_gem_final(mrb_state* mrb){
- *
- *   }
+ *     mrb_value
+ *     mrb_example_method(mrb_state *mrb){
+ *       return mrb_str_new_cstr(mrb, "example");
+ *     }
  *
+ *     void
+ *     mrb_example_gem_init(mrb_state* mrb){
+ *       struct RClass *example_class_a;
+ *       struct RClass *example_class_b;
+ *       struct RClass *example_class_c;
+ *       example_class_a = mrb_define_class(mrb, "ExampleClassA", mrb->object_class);
+ *       mrb_define_method(mrb, example_class_a, "example_method", mrb_example_method, MRB_ARGS_NONE());
+ *       example_class_b = mrb_define_class(mrb, "ExampleClassB", example_class_a);
+ *       example_class_c = mrb_define_class(mrb, "ExampleClassC", example_class_b);
+ *       mrb_undef_method(mrb, example_class_c, "example_method");
+ *     }
+ *     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*] constchar* The name of the method to be undefined.
@@ -425,47 +394,35 @@ MRB_API void mrb_undef_method(mrb_state*, struct RClass*, const char*);
 
 /**
  * Undefine a class method.
- *
  * Example:
- *   # Ruby style
- *
- *   class ExampleClass
- *     def self.example_method
- *       "example"
- *     end
  *
- *   end
+ *      # Ruby style
+ *      class ExampleClass
+ *        def self.example_method
+ *          "example"
+ *        end
+ *      end
  *
- *   ExampleClass.example_method
+ *     ExampleClass.example_method
  *   
- *   // C style
- *   #include <stdio.h>
- *   #include <mruby.h> 
- *
- *   mrb_value
- *   mrb_example_method(mrb_state *mrb){
- *
- *     return mrb_str_new_cstr(mrb, "example");
- *     
- *   }
- *
- *   void
- *   mrb_example_gem_init(mrb_state* mrb){
+ *     // C style
+ *     #include <stdio.h>
+ *     #include <mruby.h> 
  *
- *     struct RClass *example_class;
- *     
- *     example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class);
- *
- *     mrb_define_class_method(mrb, example_class, "example_method", mrb_example_method, MRB_ARGS_NONE());
- *
- *     mrb_undef_class_method(mrb, example_class, "example_method");
- *
- *   }
- *
- *   void
- *   mrb_example_gem_final(mrb_state* mrb){
- *
- *   }
+ *     mrb_value
+ *     mrb_example_method(mrb_state *mrb){
+ *       return mrb_str_new_cstr(mrb, "example");     
+ *     }
+ *     void
+ *     mrb_example_gem_init(mrb_state* mrb){
+ *       struct RClass *example_class;     
+ *       example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class);
+ *       mrb_define_class_method(mrb, example_class, "example_method", mrb_example_method, MRB_ARGS_NONE());
+ *       mrb_undef_class_method(mrb, example_class, "example_method");
+ *      }
+ *      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 [constchar*] constchar* The name of the class method to be undefined.
@@ -477,24 +434,24 @@ MRB_API void mrb_undef_class_method(mrb_state*, struct RClass*, const char*);
  *
  * Example:
  *
- *   # Ruby style
- *   class ExampleClass
- *   end
+ *     # Ruby style
+ *     class ExampleClass
+ *     end
  *
- *   p ExampleClass # => #<ExampleClass:0x9958588>
- *   // C style
- *   #include <stdio.h>
- *   #include <mruby.h>
+ *     p ExampleClass # => #<ExampleClass:0x9958588>
+ *     // C style
+ *     #include <stdio.h>
+ *     #include <mruby.h>
  *
- *   void
- *   mrb_example_gem_init(mrb_state* mrb) {
- *     struct RClass *example_class;
- *     mrb_value obj;
+ *     void
+ *     mrb_example_gem_init(mrb_state* mrb) {
+ *       struct RClass *example_class;
+ *       mrb_value obj;
  *
- *     example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class); # => class ExampleClass; end
- *     obj = mrb_obj_new(mrb, example_class, 0, NULL); # => ExampleClass.new
- *     mrb_p(mrb, obj); // => Kernel#p
- *   }  
+ *       example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class); # => class ExampleClass; end
+ *       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
@@ -516,15 +473,15 @@ MRB_API mrb_value mrb_instance_new(mrb_state *mrb, mrb_value cv);
  *
  * Example:
  *
- *   void
- *   mrb_example_gem_init(mrb_state* mrb) {
- *      struct RClass *example_class;
- *      mrb_value obj;
+ *      void
+ *      mrb_example_gem_init(mrb_state* mrb) {
+ *        struct RClass *example_class;
+ *        mrb_value obj;
  *
- *      example_class = mrb_class_new(mrb, mrb->object_class);
- *      obj = mrb_obj_new(mrb, example_class, 0, NULL); // => #<#<Class:0x9a945b8>:0x9a94588>
- *      mrb_p(mrb, obj); // => Kernel#p
- *   }
+ *        example_class = mrb_class_new(mrb, mrb->object_class);
+ *        obj = mrb_obj_new(mrb, example_class, 0, NULL); // => #<#<Class:0x9a945b8>:0x9a94588>
+ *        mrb_p(mrb, obj); // => Kernel#p
+ *       }
  *
  * @param [mrb_state*] mrb The current mruby state.
  * @param [struct RClass *] super The super class or parent.
@@ -536,12 +493,12 @@ MRB_API struct RClass * mrb_class_new(mrb_state *mrb, struct RClass *super);
  * Creates a new module, Module.
  *
  * Example:
- *   void
- *   mrb_example_gem_init(mrb_state* mrb) {
- *      struct RClass *example_module;
+ *      void
+ *      mrb_example_gem_init(mrb_state* mrb) {
+ *        struct RClass *example_module;
  *
- *      example_module = mrb_module_new(mrb);
- *   }
+ *        example_module = mrb_module_new(mrb);
+ *      }
  *
  * @param [mrb_state*] mrb The current mruby state.
  * @return [struct RClass *] Reference to the new module.
@@ -552,23 +509,23 @@ MRB_API struct RClass * mrb_module_new(mrb_state *mrb);
  * Returns an mrb_bool. True if class was defined, and false if the class was not defined.
  *
  * Example:
- *   void
- *   mrb_example_gem_init(mrb_state* mrb) {
- *      struct RClass *example_class;
- *      mrb_bool cd;
+ *     void
+ *     mrb_example_gem_init(mrb_state* mrb) {
+ *       struct RClass *example_class;
+ *       mrb_bool cd;
  *
- *      example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class);
- *      cd = mrb_class_defined(mrb, "ExampleClass");
+ *       example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class);
+ *       cd = mrb_class_defined(mrb, "ExampleClass");
  *      
- *      // If mrb_class_defined returns 1 then puts "True"
- *      // If mrb_class_defined returns 0 then puts "False"
- *      if (cd == 1){
- *        puts("True");
- *      }
- *      else {
- *        puts("False");
+ *       // If mrb_class_defined returns 1 then puts "True"
+ *       // If mrb_class_defined returns 0 then puts "False"
+ *       if (cd == 1){
+ *         puts("True");
+ *       }
+ *       else {
+ *         puts("False");
+ *       }
  *      }
- *   }
  *
  * @param [mrb_state*] mrb The current mruby state.
  * @param [const char *] name A string representing the name of the class.
@@ -627,36 +584,36 @@ MRB_API mrb_value mrb_check_to_integer(mrb_state *mrb, mrb_value val, const char
  * Returns true if obj responds to the given method. If the method was defined for that
  * class it returns true, it returns false otherwise.
  *
- * Example:
- *   # Ruby style
- *   class ExampleClass
- *      def example_method
+ *      Example:
+ *      # Ruby style
+ *      class ExampleClass
+ *        def example_method
+ *        end
  *      end
- *   end
  *
- *   ExampleClass.new.respond_to?(:example_method) # => true
+ *      ExampleClass.new.respond_to?(:example_method) # => true
  *
- *   // C style
- *   void
- *   mrb_example_gem_init(mrb_state* mrb) {
- *      struct RClass *example_class;
- *      mrb_sym mid;
- *      mrb_bool obj_resp;
+ *      // C style
+ *      void
+ *      mrb_example_gem_init(mrb_state* mrb) {
+ *        struct RClass *example_class;
+ *        mrb_sym mid;
+ *        mrb_bool obj_resp;
  *
- *      example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class);
- *      mrb_define_method(mrb, example_class, "example_method", exampleMethod, MRB_ARGS_NONE());
- *      mid = mrb_intern_str(mrb, mrb_str_new_cstr(mrb, "example_method" ));
- *      obj_resp = mrb_obj_respond_to(mrb, example_class, mid); // => 1(true in Ruby world)
+ *        example_class = mrb_define_class(mrb, "ExampleClass", mrb->object_class);
+ *        mrb_define_method(mrb, example_class, "example_method", exampleMethod, MRB_ARGS_NONE());
+ *        mid = mrb_intern_str(mrb, mrb_str_new_cstr(mrb, "example_method" ));
+ *        obj_resp = mrb_obj_respond_to(mrb, example_class, mid); // => 1(true in Ruby world)
  *      
- *      // If mrb_obj_respond_to returns 1 then puts "True"
- *      // If mrb_obj_respond_to returns 0 then puts "False"
- *      if (obj_resp == 1) {
- *        puts("True");
- *      }
- *      else if (obj_resp == 0) {
- *        puts("False");
+ *        // If mrb_obj_respond_to returns 1 then puts "True"
+ *        // If mrb_obj_respond_to returns 0 then puts "False"
+ *        if (obj_resp == 1) {
+ *          puts("True");
+ *        }
+ *        else if (obj_resp == 0) {
+ *          puts("False");
+ *        }
  *      }
- *   }
  *
  * @param [mrb_state*] mrb The current mruby state.
  * @param [struct RClass *] c A reference to a class.
@@ -794,10 +751,74 @@ mrb_get_argc(mrb_state *mrb) /* get argc */
 
 /**
  * Call existing ruby functions.
+ *
+ *      #include <stdio.h>
+ *      #include <mruby.h>
+ *      #include "mruby/compile.h"
+ *      int
+ *      main()
+ *      {
+ *        mrb_int i = 99;
+ *        mrb_state *mrb = mrb_open();
+ *        if (!mrb) { }
+ *        FILE *fp = fopen("test.rb","r");
+ *        mrb_value obj = mrb_load_file(mrb,fp);
+ *        mrb_funcall(mrb, obj, "method_name", 1, mrb_fixnum_value(i));
+ *        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.
  */
 MRB_API mrb_value mrb_funcall(mrb_state*, mrb_value, const char*, mrb_int,...);
+/**
+ * Call existing ruby functions. This is basically the type safe version of mrb_funcall.
+ * 
+ *      #include <stdio.h>
+ *      #include <mruby.h>
+ *      #include "mruby/compile.h"
+ *      int
+ *      main()
+ *      {
+ *        mrb_int i = 99;
+ *        mrb_state *mrb = mrb_open();
+ *        if (!mrb) { }
+ *        mrb_sym m_sym = mrb_intern_cstr(mrb, "method_name"); // Symbol for method.
+ *        FILE *fp = fopen("test.rb","r");
+ *        mrb_value obj = mrb_load_file(mrb,fp);
+ *        mrb_funcall_argv(mrb, obj, m_sym, 1, &obj); // Calling ruby function from test.rb.
+ *        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.
+ * @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*);
+/**
+ * Call existing ruby functions with a block.
+ */
 MRB_API mrb_value mrb_funcall_with_block(mrb_state*, mrb_value, mrb_sym, mrb_int, const mrb_value*, mrb_value);
+/**
+ * Create a symbol
+ *
+ *     # Ruby style:
+ *     :pizza # => :pizza
+ *     
+ *     // C style:
+ *     mrb_sym m_sym = mrb_intern_cstr(mrb, "pizza"); //  => :pizza
+ * @param [mrb_state*] mrb_state* The current mruby state.
+ * @param [const char*] const char* The name of the method.
+ * @return [mrb_sym] mrb_sym A symbol.
+ */
 MRB_API mrb_sym mrb_intern_cstr(mrb_state*,const char*);
 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);