Merge pull request #6536 from mruby/add-debug-comments

src/debug.c

@@ -33,6 +33,10 @@ get_file(mrb_irep_debug_info *info, uint32_t pc)
   return *ret;
 }
 
+/*
+ * Calculates the number of bytes that `mrb_packed_int_encode` will write
+ * to store the given 32-bit unsigned integer `num`.
+ */
 size_t
 mrb_packed_int_len(uint32_t num)
 {
@@ -44,6 +48,15 @@ mrb_packed_int_len(uint32_t num)
   return llen;
 }
 
+/*
+ * Encodes a 32-bit unsigned integer `num` into a variable-length packed format
+ * and writes it to the byte array `p`.
+ * The most significant bit of each byte is used as a continuation flag:
+ * - 1 indicates that more bytes follow.
+ * - 0 indicates the last byte.
+ * The lower 7 bits of each byte store parts of the number.
+ * Returns the number of bytes written to `p`.
+ */
 size_t
 mrb_packed_int_encode(uint32_t num, uint8_t *p)
 {
@@ -60,6 +73,14 @@ mrb_packed_int_encode(uint32_t num, uint8_t *p)
   return llen;
 }
 
+/*
+ * Decodes a 32-bit unsigned integer from the variable-length packed format
+ * in the byte array `p`. It reads bytes until it finds one where the most
+ * significant bit is 0.
+ * If `newpos` is not NULL, it will be updated to point to the byte
+ * following the last byte read.
+ * Returns the decoded 32-bit unsigned integer.
+ */
 uint32_t
 mrb_packed_int_decode(const uint8_t *p, const uint8_t **newpos)
 {
@@ -109,6 +130,11 @@ debug_get_line(mrb_state *mrb, mrb_irep_debug_info_file* f, uint32_t pc)
   return -1;
 }
 
+/*
+ * Retrieves the filename for a given instruction pointer (pc)
+ * within a given mruby interpreter state (mrb) and mruby bytecode (irep).
+ * Returns NULL if the information is not available.
+ */
 MRB_API char const*
 mrb_debug_get_filename(mrb_state *mrb, const mrb_irep *irep, uint32_t pc)
 {
@@ -119,6 +145,11 @@ mrb_debug_get_filename(mrb_state *mrb, const mrb_irep *irep, uint32_t pc)
   return NULL;
 }
 
+/*
+ * Retrieves the line number for a given instruction pointer (pc)
+ * within a given mruby interpreter state (mrb) and mruby bytecode (irep).
+ * Returns -1 if the information is not available.
+ */
 MRB_API int32_t
 mrb_debug_get_line(mrb_state *mrb, const mrb_irep *irep, uint32_t pc)
 {
@@ -129,6 +160,13 @@ mrb_debug_get_line(mrb_state *mrb, const mrb_irep *irep, uint32_t pc)
   return -1;
 }
 
+/*
+ * Retrieves both the filename and line number for a given instruction pointer (pc)
+ * within a given mruby interpreter state (mrb) and mruby bytecode (irep).
+ * The line number is stored in the `lp` output parameter and the filename in the `fp` output parameter.
+ * Returns TRUE if the information is successfully retrieved, and FALSE otherwise.
+ * In case of failure, `lp` is set to -1 and `fp` is set to NULL.
+ */
 MRB_API mrb_bool
 mrb_debug_get_position(mrb_state *mrb, const mrb_irep *irep, uint32_t pc, int32_t *lp, const char **fp)
 {
@@ -144,6 +182,12 @@ mrb_debug_get_position(mrb_state *mrb, const mrb_irep *irep, uint32_t pc, int32_
   return FALSE;
 }
 
+/*
+ * Allocates and initializes a new `mrb_irep_debug_info` structure
+ * for a given mruby interpreter state (mrb) and mruby bytecode (irep).
+ * This function asserts that debug_info is not already allocated for the irep.
+ * Returns a pointer to the newly allocated `mrb_irep_debug_info` structure.
+ */
 MRB_API mrb_irep_debug_info*
 mrb_debug_info_alloc(mrb_state *mrb, mrb_irep *irep)
 {
@@ -156,6 +200,16 @@ mrb_debug_info_alloc(mrb_state *mrb, mrb_irep *irep)
   return ret;
 }
 
+/*
+ * Appends a new file's debug information to an existing `mrb_irep_debug_info` structure `d`.
+ * It takes the mruby state `mrb`, the debug info structure `d`, the `filename`,
+ * an array of `lines` numbers, the `start_pos` (starting program counter for this file),
+ * and `end_pos` (ending program counter for this file).
+ * `filename` and `lines` must not be NULL.
+ * Returns a pointer to the newly created `mrb_irep_debug_info_file` structure,
+ * or NULL if `d` is NULL, `start_pos` equals `end_pos`, or if the filename is
+ * the same as the previously appended file.
+ */
 MRB_API mrb_irep_debug_info_file*
 mrb_debug_info_append_file(mrb_state *mrb, mrb_irep_debug_info *d,
                            const char *filename, uint16_t *lines,
@@ -212,6 +266,12 @@ mrb_debug_info_append_file(mrb_state *mrb, mrb_irep_debug_info *d,
   return f;
 }
 
+/*
+ * Frees the memory allocated for an `mrb_irep_debug_info` structure `d`
+ * and all its associated data, including file information and line data.
+ * It takes the mruby state `mrb` and the debug info structure `d` to be freed.
+ * If `d` is NULL, the function does nothing.
+ */
 MRB_API void
 mrb_debug_info_free(mrb_state *mrb, mrb_irep_debug_info *d)
 {