Hello @matz, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

Summary of Changes

Hello! Gemini here, providing a summary of this pull request to help everyone quickly understand the changes.

The intent of this PR, as described by the author @matz, is to significantly improve the documentation of the MRB_API functions within the src/class.c file. This is being achieved by adding detailed C-style block comments (/* ... */) to each public API function. These comments aim to clearly explain the purpose of each function, detail its parameters using @param tags, describe its return value using @return, and note any potential side effects (@sideeffect) or exceptions raised (@raise). The overall goal is to enhance code readability and maintainability for developers working with the mruby C API.

Highlights

API Documentation: Adds comprehensive C-style block comments to numerous MRB_API functions in src/class.c.
Improved Readability: Comments include details on function purpose, parameters, return values, side effects, and potential exceptions.
Maintainability: Clearer documentation makes it easier for developers to understand and correctly use the mruby C API related to classes and modules.

Changelog

Click here to see the changelog

src/class.c
- Added C-style block comments to mrb_mt_foreach describing its purpose, parameters, and return value.
- Added C-style block comments to mrb_define_module_id and mrb_define_module detailing their purpose, parameters, return, and side effects.
- Added C-style block comments to mrb_define_module_under_id and mrb_define_module_under detailing their purpose, parameters, return, and side effects.
- Added C-style block comments to mrb_define_class_id and mrb_define_class detailing their purpose, parameters, return, side effects, and potential warnings/raises.
- Added C-style block comments to mrb_class_defined, mrb_class_defined_id, mrb_class_defined_under, and mrb_class_defined_under_id explaining their purpose, parameters, and return value.
- Added C-style block comments to mrb_class_get_under, mrb_class_get_under_id, mrb_class_get, and mrb_class_get_id detailing their purpose, parameters, return, and potential raises.
- Added C-style block comments to mrb_exc_get_id detailing its purpose, parameters, return, and potential raises.
- Added C-style block comments to mrb_module_get_under, mrb_module_get_under_id, mrb_module_get, and mrb_module_get_id detailing their purpose, parameters, return, and potential raises.
- Replaced existing /*! ... */ comments with C-style block comments for mrb_define_class_under_id and mrb_define_class_under, adding more detailed @param, @return, @raise, and @sideeffect tags.
- Added C-style block comments to mrb_define_method_raw detailing its purpose, parameters, side effects, and potential raises.
- Added C-style block comments to mrb_define_method_id, mrb_define_method, mrb_define_private_method_id, and mrb_define_private_method detailing their purpose, parameters, and side effects.
- Added C-style block comments to mrb_notimplement explaining its purpose and side effects.
- Added C-style block comments to mrb_notimplement_m explaining its purpose, parameters, return, and side effects.
- Added C-style block comments to mrb_get_argc explaining its purpose and return value.
- Added C-style block comments to mrb_get_argv explaining its purpose, return value, and notes on argument packing.
- Added C-style block comments to mrb_get_arg1 explaining its purpose, return value, and potential raises.
- Added C-style block comments to mrb_block_given_p explaining its purpose and return value.
- Replaced existing /*! ... */ comments with C-style block comments for mrb_get_args, adding detailed explanations of format specifiers and modifiers, parameters, return, raises, and side effects.
- Added C-style block comments to mrb_get_args_a explaining its purpose, parameters, return, raises, and side effects.
- Added C-style block comments to mrb_include_module explaining its purpose, parameters, raises, and side effects.
- Added C-style block comments to mrb_prepend_module explaining its purpose, parameters, raises, and side effects.
- Added C-style block comments to mrb_obj_extend explaining its purpose, parameters, return, raises, and side effects.
- Added C-style block comments to mrb_singleton_class_ptr explaining its purpose, parameters, return, and side effects.
- Added C-style block comments to mrb_singleton_class explaining its purpose, parameters, return, raises, and side effects.
- Added C-style block comments to mrb_define_singleton_method and mrb_define_singleton_method_id explaining their purpose, parameters, raises, and side effects.
- Added C-style block comments to mrb_define_class_method and mrb_define_class_method_id explaining their purpose, parameters, raises, and side effects.
- Added C-style block comments to mrb_define_module_function_id and mrb_define_module_function explaining their purpose, parameters, and side effects.
- Added C-style block comments to mrb_undef_method_id and mrb_undef_method explaining their purpose, parameters, raises, and side effects.
- Added C-style block comments to mrb_undef_class_method_id and mrb_undef_class_method explaining their purpose, parameters, raises, and side effects.
- Added C-style block comments to mrb_remove_method explaining its purpose, parameters, raises, and side effects.
- Replaced existing /*! ... */ comments with C-style block comments for mrb_obj_clone, adding detailed explanations of purpose, parameters, return, raises, and side effects.
- Replaced existing /*! ... */ comments with C-style block comments for mrb_obj_dup, adding detailed explanations of purpose, parameters, return, raises, and side effects.
- Replaced existing /*! ... */ comments with C-style block comments for mrb_obj_class explaining its purpose, parameters, return, and side effects.
- Replaced existing /*! ... */ comments with C-style block comments for mrb_alias_method, mrb_define_alias, and mrb_define_alias_id explaining their purpose, parameters, raises, and side effects.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Code needs guiding light,
Comments bloom in blocky style,
API made clear.

Footnotes

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩