Added documentation on function for globals

1 files changed, 58 insertions, 0 deletions

diff --git a/include/mruby/variable.h b/include/mruby/variable.h
index 15068039a..8b1cc2eef 100644
--- a/include/mruby/variable.h
+++ b/include/mruby/variable.h
@@ -54,9 +54,67 @@ MRB_API mrb_bool mrb_iv_defined(mrb_state*, mrb_value, mrb_sym);
 MRB_API mrb_value mrb_iv_remove(mrb_state *mrb, mrb_value obj, mrb_sym sym);
 MRB_API void mrb_iv_copy(mrb_state *mrb, mrb_value dst, mrb_value src);
 MRB_API mrb_bool mrb_const_defined_at(mrb_state *mrb, mrb_value mod, mrb_sym id);
+
+/**
+ * Get a global variable. Will return nil if the var does not exist
+ *
+ * Example:
+ *
+ *     !!!ruby
+ *     # Ruby style
+ *     var = $value
+ *
+ *     !!!c
+ *     // C style
+ *     mrb_sym sym = mrb_intern_cstr(mrb, "$value");
+ *     mrb_value var = mrb_gv_get(mrb, sym);
+ *
+ * @param mrb The mruby state reference
+ * @param sym The name of the global variable
+ * @return The value of that global variable. May be nil
+ */
 MRB_API mrb_value mrb_gv_get(mrb_state *mrb, mrb_sym sym);
+
+/**
+ * Set a global variable
+ *
+ * Example:
+ *
+ *     !!!ruby
+ *     # Ruby style
+ *     $value = "foo"
+ *
+ *     !!!c
+ *     // C style
+ *     mrb_sym sym = mrb_intern_cstr(mrb, "$value");
+ *     mrb_gv_set(mrb, sym, mrb_str_new_cstr("foo"));
+ *
+ * @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_set(mrb_state *mrb, mrb_sym sym, mrb_value val);
+
+/**
+ * Remove a global variable.
+ *
+ * Example:
+ *
+ *     !!!ruby
+ *     # Ruby style
+ *     $value = nil
+ *
+ *     !!!c
+ *     // C style
+ *     mrb_sym sym = mrb_intern_cstr(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);
+
 MRB_API mrb_value mrb_cv_get(mrb_state *mrb, mrb_value mod, mrb_sym sym);
 MRB_API void mrb_mod_cv_set(mrb_state *mrb, struct RClass * c, mrb_sym sym, mrb_value v);
 MRB_API void mrb_cv_set(mrb_state *mrb, mrb_value mod, mrb_sym sym, mrb_value v);