MDBF-1224: fix the structure of the plugin MD file - #5617
Open
gkodinov wants to merge 1 commit into
Open
Conversation
Member
Author
|
This is how the generated docs look like on my end: |
There was a problem hiding this comment.
Pull request overview
This PR restructures the MariaDB Server Plugin API documentation by introducing a hierarchical Doxygen group layout (intended for Moxygen 2.1.16+) and expanding the top-level conceptual documentation, so the generated Plugin API docs have a clearer, navigable structure.
Changes:
- Added/standardized Doxygen groups (
@defgroup/@addtogroup,@{/@}) across Plugin API service and plugin-type headers. - Expanded the Plugin API main page and added conceptual/implementation pages in
include/mysql/index.dox. - Tightened doc-generation requirements by enforcing Moxygen 2.1.16 and updating Doxygen predefined macros used for generation.
Reviewed changes
Copilot reviewed 60 out of 60 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| include/mysql/services.h | Add Plugin Services Doxygen group + adjust include guard placement |
| include/mysql/service_wsrep.h | Add WSREP service group + inline docs + macro parameter naming |
| include/mysql/service_thd.h | Add THD service group + adjust include guard placement |
| include/mysql/service_thd_wait.h | Add THD Wait service group + reorganize docs |
| include/mysql/service_thd_timezone.h | Add THD Timezone service group + doc formatting |
| include/mysql/service_thd_specifics.h | Add THD Specifics group + refactor dynamic-plugin macro section |
| include/mysql/service_thd_rnd.h | Add THD RND group + refactor dynamic-plugin macro section |
| include/mysql/service_thd_mdl.h | Add THD MDL group + refactor dynamic-plugin macro section |
| include/mysql/service_thd_error_context.h | Add THD error context group + fix include guard naming + macro section |
| include/mysql/service_thd_autoinc.h | Add THD autoinc group + refactor dynamic-plugin macro section |
| include/mysql/service_thd_alloc.h | Add THD alloc group + refactor dynamic-plugin macro section |
| include/mysql/service_sql.h | Add SQL service group + improve function list formatting |
| include/mysql/service_sha2.h | Add SHA2 service group + rename macro params + variadic macro wrapper |
| include/mysql/service_sha1.h | Add SHA1 service group + rename macro params + variadic macro wrapper |
| include/mysql/service_progress_report.h | Add Progress Report group + doc formatting |
| include/mysql/service_print_check_msg.h | Add Print Check Msg group + adjust service function signature naming |
| include/mysql/service_my_snprintf.h | Add My Snprintf group + restructure declarations + macro wrappers |
| include/mysql/service_my_print_error.h | Add My Print Error group + group scoping |
| include/mysql/service_my_crypt.h | Add My Crypt group + group scoping |
| include/mysql/service_md5.h | Add MD5 service group + group scoping |
| include/mysql/service_logger.h | Add Logger group + doc formatting |
| include/mysql/service_log_warnings.h | Add Log Warnings group + improve accessor docs |
| include/mysql/service_kill_statement.h | Add KILL statement group + clarify return semantics |
| include/mysql/service_json.h | Add JSON service group + doc formatting + group scoping |
| include/mysql/service_encryption.h | Add Encryption service group + include guard placement |
| include/mysql/service_encryption_scheme.h | Add Encryption scheme service group + group scoping |
| include/mysql/service_debug_sync.h | Add Debug Sync group + modernize doc formatting + include guard placement |
| include/mysql/service_base64.h | Add Base64 service group + include guard placement |
| include/mysql/psi/psi.h | Introduce Instrumentation Interface group nearer the include guard |
| include/mysql/psi/psi_memory.h | Switch to @addtogroup Instrumentation_interface |
| include/mysql/psi/psi_base.h | Switch to @addtogroup + adjust group close placement |
| include/mysql/psi/psi_abi_v2.h | Wrap ABI include in @addtogroup Instrumentation_interface |
| include/mysql/psi/psi_abi_v1.h | Wrap ABI include in @addtogroup Instrumentation_interface |
| include/mysql/psi/psi_abi_v0.h | Wrap ABI include in @addtogroup Instrumentation_interface |
| include/mysql/psi/mysql_transaction.h | Move PSI_TRANSACTION_CALL guard below group header |
| include/mysql/psi/mysql_thread.h | Move Thread instrumentation group to top of file section |
| include/mysql/psi/mysql_table.h | Move Table instrumentation group to top of file section |
| include/mysql/psi/mysql_statement.h | Move Statement instrumentation group to top of file section |
| include/mysql/psi/mysql_stage.h | Move Stage instrumentation group to top of file section |
| include/mysql/psi/mysql_sp.h | Add Stored Programs instrumentation group + close group |
| include/mysql/psi/mysql_socket.h | Move Socket instrumentation group to top of file section |
| include/mysql/psi/mysql_ps.h | Add Prepared Statements instrumentation group + close group |
| include/mysql/psi/mysql_memory.h | Move Memory instrumentation group to include-guard section |
| include/mysql/psi/mysql_mdl.h | Move Metadata instrumentation group to top of file section |
| include/mysql/psi/mysql_idle.h | Move Idle instrumentation group to top of file section |
| include/mysql/psi/mysql_file.h | Move PSI_FILE_CALL guard below group header |
| include/mysql/plugin.h | Add top-level Plugin API groups + restructure/annotate plugin declaration & types docs |
| include/mysql/plugin_password_validation.h | Add Password Validation plugin group + include guard placement |
| include/mysql/plugin_function.h | Add Function plugin group + doc cleanup |
| include/mysql/plugin_ftparser.h | Add Full-text Parser plugin group + heavy doc/comment refactor |
| include/mysql/plugin_encryption.h | Add Encryption plugin group + restructure documentation |
| include/mysql/plugin_data_type.h | Add Data Type plugin group + doc cleanup |
| include/mysql/plugin_auth.h | Add Authentication plugin group + reorganize/annotate related constants |
| include/mysql/plugin_auth_common.h | Add authentication @addtogroup + return-code subgroup |
| include/mysql/plugin_audit.h | Add Audit plugin group + add subgroups for audit classes |
| include/mysql/index.dox | Expand main page + add Concepts and Implementation pages |
| include/mysql/generate_plugin_api_docs.sh | Add Moxygen version check (2.1.16) before generating docs |
| include/mysql/Doxyfile.generated_docs_plugin_api | Extend PREDEFINED macros for doc generation |
| include/mysql/client_plugin.h | Add Client Plugin API group + include guard placement |
| include/mysql/auth_dialog_client.h | Add Client Plugin API subgroup references + include guard placement |
Suppressed comments (2)
include/mysql/index.dox:28
- Minor grammar/spelling in the concepts text: "These API" should be plural (APIs) and "implementions" should be "implementations".
These API are like written functionality contracts.
They allow separating the server functionality from the actual API
implementations themselves. And, since the API implementions are a dynamic set,
adding new implementations extends the server functionality
include/mysql/index.dox:130
- Typo: "auxilary" → "auxiliary".
_maria_sizeof_struct_st_plugin_, but these are auxilary.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
118
to
+121
| #ifdef MYSQL_DYNAMIC_PLUGIN | ||
|
|
||
| #define my_vsnprintf my_snprintf_service->my_vsnprintf_type | ||
| #define my_snprintf my_snprintf_service->my_snprintf_type | ||
| #define my_snprintf(to, n, fmt, ...) my_snprintf_service->my_snprintf_type(to, n, fmt, __VA_ARGS__) | ||
| #define my_vsnprintf(to, n, fmt, ap) my_snprintf_service->my_vsnprintf_type(to, n, fmt, ap) |
Member
There was a problem hiding this comment.
yup. Old definition was not a mistake or omission.
Member
Author
There was a problem hiding this comment.
this is IMHO an improvement.
Member
There was a problem hiding this comment.
See again, what Copilot wrote. It doesn't work, it creates code that doesn't compile.
gkodinov
force-pushed
the
main-mdbf-1224
branch
from
August 31, 2026 11:52
aa63464 to
d45c03c
Compare
vuvova
reviewed
Aug 31, 2026
|
|
||
| #check if moxygen version is good enough | ||
| moxygen_version=$(moxygen --version) | ||
| require_moxygen_version="2.1.16" |
Member
There was a problem hiding this comment.
fine, as you like. Although, because it's bash I'd do
highest_of_two=$((echo $moxygen_version;echo $require_moxygen_version)|sort -V|tail -n1)
if [[ "$highest_of_two" != $moxygen_version ]]' thenwhich is ~25 lines shorter and more bash-idiomatic.
| How to declare a plugin to the server. | ||
|
|
||
| Macros for beginning and ending plugin declarations. | ||
| Between @ref mysql_declare_plugin and @ref mysql_declare_plugin_end |
Member
There was a problem hiding this comment.
maria_declare_plugin etc.
mysql_declare_plugin is for compatibility with MySQL plugins and I'm not even sure it still works
| */ | ||
|
|
||
| #define PLUGIN_OPT_NO_INSTALL 1UL /**< Not dynamically loadable */ | ||
| #define PLUGIN_OPT_NO_UNINSTALL 2UL /**< Not dynamically unloadable */ |
Member
There was a problem hiding this comment.
I don't think these are used, better change the comment to
/**< Unused */| @defgroup plugin_api_service_direct Services for direct access to server internals | ||
| @ingroup plugin_api_services_for_plugins | ||
|
|
||
| These are callbacks to the server that circumvent the normal plugin service APIs |
Comment on lines
118
to
+121
| #ifdef MYSQL_DYNAMIC_PLUGIN | ||
|
|
||
| #define my_vsnprintf my_snprintf_service->my_vsnprintf_type | ||
| #define my_snprintf my_snprintf_service->my_snprintf_type | ||
| #define my_snprintf(to, n, fmt, ...) my_snprintf_service->my_snprintf_type(to, n, fmt, __VA_ARGS__) | ||
| #define my_vsnprintf(to, n, fmt, ap) my_snprintf_service->my_vsnprintf_type(to, n, fmt, ap) |
Member
There was a problem hiding this comment.
yup. Old definition was not a mistake or omission.
This requires moxygen 2.1.16! Added a check Implemented a structure for the plugin API documentation. On the top there's a main page to give top level overview and concepts. It eventually references the Moxygen documentation. The moxygen documentation is a series of nested doxygen groups that define the structure for the whole Plugin API documentation. There are top levels like "server plugin API" and "client plugin API". These branch into futher subgroups as needed. Addressed githib copilot review comments.
gkodinov
force-pushed
the
main-mdbf-1224
branch
from
August 31, 2026 12:40
d45c03c to
7464dc2
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This requires moxygen 2.1.16! Added a check
Implemented a structure for the plugin API documentation. On the top there's a main page to give top level overview and concepts.
It eventually references the Moxygen documentation. The moxygen documentation is a series of nested doxygen groups that define the structure for the whole Plugin API documentation.
There are top levels like "server plugin API" and "client plugin API". These branch into futher subgroups as needed.