From a0526418cecec6d5053361250986ddee3e94c3df Mon Sep 17 00:00:00 2001
From: dearblue <dearblue@users.osdn.me>
Date: Fri, 26 Apr 2024 22:05:45 +0900
Subject: [PATCH] Update documentation for `mrb_top_run()`

Also, add explanations for the `mrb_load_irep()` and `mrb_load_string()` families, which are indirect calls to `mrb_top_run()`.
---
 include/mruby.h         | 22 ++++++++++++++++++++++
 include/mruby/compile.h | 25 ++++++++++++++++---------
 include/mruby/irep.h    | 25 ++++++++++++++++---------
 3 files changed, 54 insertions(+), 18 deletions(-)

diff --git a/include/mruby.h b/include/mruby.h
index c5cbeca7ef..3b4a1fc729 100644
--- a/include/mruby.h
+++ b/include/mruby.h
@@ -1277,7 +1277,29 @@ MRB_API void mrb_close(mrb_state *mrb);
 MRB_API void* mrb_default_allocf(mrb_state*, void*, size_t, void*);
 
 MRB_API mrb_value mrb_top_self(mrb_state *mrb);
+
+/**
+ * Enter the mruby VM and execute the proc.
+ *
+ * @param mrb
+ *      The current mruby state.
+ * @param proc
+ *      An object containing `irep`.
+ *      If supplied an object containing anything other than `irep`, it will probably crash.
+ * @param self
+ *      `self` on the execution context of `proc`.
+ * @param stack_keep
+ *      Specifies the number of values to hold from the stack top.
+ *      Values on the stack outside this range will be initialized to `nil`.
+ *
+ * @note
+ *      When called from a C function defined as a method, the current stack is destroyed.
+ *      If you want to use arguments obtained by `mrb_get_args()` or other methods after `mrb_top_run()`,
+ *      you must protect them by `mrb_gc_protect()` or other ways before this function.
+ *      Or consider using `mrb_yield()` family functions.
+ */
 MRB_API mrb_value mrb_top_run(mrb_state *mrb, const struct RProc *proc, mrb_value self, mrb_int stack_keep);
+
 MRB_API mrb_value mrb_vm_run(mrb_state *mrb, const struct RProc *proc, mrb_value self, mrb_int stack_keep);
 MRB_API mrb_value mrb_vm_exec(mrb_state *mrb, const struct RProc *proc, const mrb_code *iseq);
 /* compatibility macros */
diff --git a/include/mruby/compile.h b/include/mruby/compile.h
index e3d0d619e1..cff9a28b4e 100644
--- a/include/mruby/compile.h
+++ b/include/mruby/compile.h
@@ -190,15 +190,22 @@ MRB_API struct mrb_parser_state* mrb_parse_nstring(mrb_state*,const char*,size_t
 MRB_API struct RProc* mrb_generate_code(mrb_state*, struct mrb_parser_state*);
 MRB_API mrb_value mrb_load_exec(mrb_state *mrb, struct mrb_parser_state *p, mrb_ccontext *c);
 
-/** program load functions
-* Please note! Currently due to interactions with the GC calling these functions will
-* leak one RProc object per function call.
-* To prevent this save the current memory arena before calling and restore the arena
-* right after, like so
-* int ai = mrb_gc_arena_save(mrb);
-* mrb_value status = mrb_load_string(mrb, buffer);
-* mrb_gc_arena_restore(mrb, ai);
-*/
+/**
+ * program load functions
+ *
+ * Please note! Currently due to interactions with the GC calling these functions will
+ * leak one RProc object per function call.
+ * To prevent this save the current memory arena before calling and restore the arena
+ * right after, like so
+ *
+ *      int ai = mrb_gc_arena_save(mrb);
+ *      mrb_value status = mrb_load_string(mrb, buffer);
+ *      mrb_gc_arena_restore(mrb, ai);
+ *
+ * Also, when called from a C function defined as a method, the current stack is destroyed.
+ * If processing continues after this function, the objects obtained from the arguments
+ * must be protected as needed before this function.
+ */
 #ifndef MRB_NO_STDIO
 MRB_API mrb_value mrb_load_file(mrb_state*,FILE*);
 MRB_API mrb_value mrb_load_file_cxt(mrb_state*,FILE*, mrb_ccontext *cxt);
diff --git a/include/mruby/irep.h b/include/mruby/irep.h
index 68e89257ad..580db1d9cf 100644
--- a/include/mruby/irep.h
+++ b/include/mruby/irep.h
@@ -84,15 +84,22 @@ struct mrb_irep {
 
 MRB_API mrb_irep *mrb_add_irep(mrb_state *mrb);
 
-/** load mruby bytecode functions
-* Please note! Currently due to interactions with the GC calling these functions will
-* leak one RProc object per function call.
-* To prevent this save the current memory arena before calling and restore the arena
-* right after, like so
-* int ai = mrb_gc_arena_save(mrb);
-* mrb_value status = mrb_load_irep(mrb, buffer);
-* mrb_gc_arena_restore(mrb, ai);
-*/
+/**
+ * load mruby bytecode functions
+ *
+ * Please note! Currently due to interactions with the GC calling these functions will
+ * leak one RProc object per function call.
+ * To prevent this save the current memory arena before calling and restore the arena
+ * right after, like so
+ *
+ *      int ai = mrb_gc_arena_save(mrb);
+ *      mrb_value status = mrb_load_irep(mrb, buffer);
+ *      mrb_gc_arena_restore(mrb, ai);
+ *
+ * Also, when called from a C function defined as a method, the current stack is destroyed.
+ * If processing continues after this function, the objects obtained from the arguments
+ * must be protected as needed before this function.
+ */
 
 /* @param [const uint8_t*] irep code, expected as a literal */
 MRB_API mrb_value mrb_load_irep(mrb_state*, const uint8_t*);