This commit adds Doxygen-style comments to several MRB_API functions
in src/vm.c to improve code readability and documentation.
The following functions were commented:
- mrb_stack_extend
- mrb_protect_error
- mrb_funcall
- mrb_funcall_id
- mrb_funcall_with_block
- mrb_funcall_argv
- mrb_yield_with_class
- mrb_yield_argv
- mrb_yield
- mrb_vm_run
- mrb_vm_exec
- mrb_top_run
Additionally, the parameter name 'self' in mrb_yield_with_class was
renamed to 'self_obj' for better clarity and consistency with the new comment.
This commit corrects the placement of C-style block comments
for MRB_API functions in src/variable.c. Comments are now
placed directly before each function definition as per standard
documentation practices.
This commit adds descriptive comments to the following MRB_API functions in src/state.c, clarifying their purpose and functionality:
- mrb_open_core
- mrb_open
- mrb_free_context
- mrb_close
- mrb_add_irep
- mrb_top_self
- mrb_state_atexit
This commit adds Doxygen-style comments to the following MRB_API functions in src/proc.c:
- mrb_proc_new_cfunc
- mrb_proc_new_cfunc_with_env
- mrb_closure_new_cfunc
- mrb_proc_cfunc_env_get
The comments describe the purpose, parameters, and return value of each function.
This commit adds descriptive C-style comments to the following functions
in `src/kernel.c`:
- `mrb_func_basic_p`: Explains that the function checks if an object's method is implemented by a specific C function.
- `mrb_obj_freeze`: Explains that the function freezes an object, preventing further modifications.
- `mrb_obj_is_instance_of`: Explains that the function checks if an object is an instance of a given class.
This commit adds Doxygen-style comments to several MRB_API functions
in the `src/etc.c` file. These comments explain the purpose,
parameters, and return values of these functions, improving code
readability and maintainability.
The following functions were commented:
- mrb_data_object_alloc
- mrb_data_check_type
- mrb_data_check_get_ptr
- mrb_data_get_ptr
- mrb_obj_to_sym
- mrb_obj_id
- mrb_word_boxing_float_value
- mrb_word_boxing_value_float
- mrb_word_boxing_cptr_value
- mrb_boxing_int_value
This commit adds descriptive comments to the following functions:
- mrb_range_ptr
- mrb_range_new
- mrb_range_beg_len
The comments were written by Google Jules.
This commit adds C-style block comments to all MRB_API functions
defined in the src/class.c file. The comments explain the purpose
of each function, its parameters, and its return value, aiming to
improve code readability and maintainability.
This commit adds Doxygen-style comments to the following functions
in src/dump.c, ensuring "@brief" is not used:
Non-static functions (comments reviewed/updated):
- mrb_dump_irep
- mrb_dump_irep_binary
- mrb_dump_irep_cfunc
Static functions (new comments added):
- write_irep_header
- write_iseq_block
- dump_float (if compiled)
- get_pool_block_size
- write_pool_block
- get_syms_block_size
- write_syms_block
- get_irep_record_size
This work is part of a larger effort to document all non-trivial
functions in this file as per your feedback. The remaining functions
will be documented in subsequent commits.
This commit adds descriptive comments to all functions marked with MRB_API
in the `src/symbol.c` file. The comments explain the purpose, parameters,
and return values of these functions, improving code readability and
maintainability.
The following functions were commented:
- mrb_intern
- mrb_intern_static
- mrb_intern_cstr
- mrb_intern_str
- mrb_intern_check
- mrb_check_intern
- mrb_intern_check_cstr
- mrb_check_intern_cstr
- mrb_intern_check_str
- mrb_check_intern_str
- mrb_sym_name_len
- mrb_sym_str
- mrb_sym_name
- mrb_sym_dump
This change adds C-style multiline comments to all functions
marked with MRB_API in the src/array.c file.
The comments explain each function's purpose, its parameters,
and what it returns, where applicable. This improves the
readability and maintainability of the C API for mruby arrays.
The `@brief` markup was intentionally avoided as per your
requirements.
This commit adds C-style descriptive comments to MRB_API functions
in `src/hash.c` that are intended for use as part of mruby's C API.
The comments are targeted at C developers using these functions directly.
Comments were added or updated for the following functions:
- mrb_hash_new: Added comment.
- mrb_hash_new_capa: Updated existing comment to be more C API user-centric.
- mrb_hash_dup: Added comment.
- mrb_hash_get: Added comment.
- mrb_hash_fetch: Added comment.
- mrb_hash_set: Added comment.
- mrb_hash_delete_key: Added comment.
- mrb_hash_size: Added comment.
- mrb_hash_merge: Added comment.
- mrb_hash_foreach: Comment updated in a previous phase of work.
This work aligns with the guideline to comment C-facing MRB_API functions,
while avoiding adding new C-API comments to those MRB_API functions
that solely implement Ruby methods and already have extensive Ruby
method documentation (call-seq) in the source. The @brief markup
was avoided as per the original issue request.
This commit adds and updates C-style block comments for all functions marked with MRB_API in src/object.c.
The comments explain the purpose, parameters, and return values of these functions, adhering to the project's documentation style and avoiding the use of '@brief' markup.
Existing comments were also reviewed and updated for clarity and consistency.
Add descriptive comments for MRB_API functions in src/string.c
This commit adds descriptive comments to various MRB_API functions
within the src/string.c file. These comments aim to improve code
readability and maintainability by explaining the purpose,
parameters, and return values of these functions.
This change adds Doxygen-style comments to the public API functions
in `src/debug.c`, including mrb_packed_int_len, mrb_packed_int_encode,
and mrb_packed_int_decode. The comments explain the purpose of each function,
its parameters, and its return value. This improves the readability
and maintainability of the code.
This commit adds Doxygen-style comments to the public functions,
internal static functions, and structs within the `src/mempool.c` file.
These comments clarify the purpose, parameters, and return values (where applicable)
of these code elements, improving code readability and maintainability.
The following elements were commented:
- struct mempool_page
- struct mempool
- ALIGN_PADDING macro
- mempool_open()
- mempool_close()
- page_alloc()
- mempool_alloc()
- mempool_realloc()
This commit adds a descriptive comment at the beginning of the `mrb_read_float` function in `src/readfloat.c`.
The comment explains the function's purpose, its parameters (`str`, `endp`, `fp`), and its return value (`TRUE` or `FALSE`). This improves code readability and understanding.
The sorted array binary search implementation no longer uses the inline
cache array, so remove all MRB_INLINE_METHOD_CACHE definitions and
related code.
By replacing the open‐addressing hash with a sorted array and binary
search, we eliminate tombstone management and improve cache locality of
method entries. This preserves the original contiguous values+keys
layout and peak memory usage, while simplifying growth logic and
delivering lookup performance gains.
Preserve the original iv_tbl heap layout and allocation pattern, but
switch iv_put to maintain sorted keys and iv_get/iv_del to perform
binary search. This eliminates extra probing overhead, improves
read-heavy lookup performance for small tables, and incurs zero
additional allocations.
My previous attempts to improve method table (mt_tbl) performance by introducing a load factor and adjusting the initial allocation size unfortunately led to undesirable increases in memory consumption.
Given that memory usage is a primary concern, I've reverted the following changes:
- Removed the load factor based rehashing logic.
- Removed the related definitions for the load factor.
- Ensured the initial allocation size is 8.
This restores the method table to its original behavior, where it rehashes only when the table is completely full or during initial allocation. This should bring memory usage back to its baseline level prior to these optimization attempts.
The method table (mt_tbl) in src/class.c previously only rehashed when it became completely full. With linear probing, this could lead to significant performance degradation for lookups and insertions as the table approached full capacity.
This change introduces a load factor (MT_LOAD_FACTOR_NUM/MT_LOAD_FACTOR_DEN, set to 3/4 or 0.75). The mt_put function now checks if adding a new element would cause the table's size to meet or exceed this load factor relative to its allocated capacity. If so, it triggers a rehash before inserting the new element.
This helps maintain more empty slots in the hash table, improving the average-case performance of linear probing and reducing the likelihood of worst-case scenarios. The existing initial allocation size and doubling strategy for rehashing are retained.
Yukihiro "Matz" Matsumoto