MDBF-1224: fix the structure of the plugin MD file

[gkodinov]

This requires moxygen 2.1.19! 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.

[gkodinov]

This is how the generated docs look like on my end:
mdbf-1224-generated-docs.tar.gz

[Copilot]

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.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved API compatibility, include-guard, documentation-generation, and copy/paste example issues remain.

Review effort: Lite
Findings: 1 · 3 · 3

Open (7)

• Restore include guard for public header · New
• Enforce documented moxygen version requirement · New
• Preserve dynamic my_sha1_multi alias form · New
• Preserve dynamic my_sha224_multi alias form · New
• Fix misspelling of implementations · New
• Fix misspelling of independency · New
• Fix ligther and knowning misspellings · New

Resolved since last review (7)

• Under MYSQL_DYNAMIC_PLUGIN this header does not provide a print_check_msg(...) entry point (only…
• The variadic macro wrapper for my_snprintf forwards VA_ARGS unconditionally, which breaks valid…
• Typo: "seach" → "search".
• The description of the 'sQ' format extension currently says it quotes with "\'" while calling it…
• Typo in section title: "Bicture" → "Picture". This issue also appears in the following locations of…
• The placeholder in the quoted error message is written as "@​%s", but printf-style placeholders…
• The wait-type enum comments are inconsistent with the surrounding documentation and naming:…

[Copilot]

Copilot review overview

🟡 Changes recommended

Critical API and version-check issues, plus invalid documentation examples, remain unresolved.

Review effort: Lite
Findings: 2 · 1 · 2

Open (5)

• Extract numeric version before calling vercmp · New
• Preserve direct my_sha256_multi alias · New
• Fix misspelled v1_check_function callback · New
• Correct vercmp return-value documentation · New
• Retain thd_wait_begin and thd_wait_end pairing · New

Resolved since last review (7)

• Restore include guard for public header
• Preserve dynamic my_sha224_multi alias form
• Preserve dynamic my_sha1_multi alias form
• Enforce documented moxygen version requirement
• Fix ligther and knowning misspellings
• Fix misspelling of independency
• Fix misspelling of implementations

[Copilot]

🟡 Changes recommended

WSREP wrapper macros reference undeclared service members and must be corrected before approval.

11 open findings

• Use wsrep_report_bf_lock_wait_func in wrapper · New
• Use wsrep_thd_set_wsrep_PA_unsafe_func in wrapper · New
• Fix misspelling of exported · New
• Fix misspelling of successful · New
• Fix misspelling of declaration · New
• Fix misspelling of facilitate · New
• Fix misspelling of defaulted · New
• Fix misspelling of array · New
• Fix misspelling of whatsoever · New
• Correct daemon plugin group description · New
• Document the accessor's integer log warning level · New

5 resolved since last review

• Preserve direct my_sha256_multi alias
• Extract numeric version before calling vercmp
• Fix misspelled v1_check_function callback
• Retain thd_wait_begin and thd_wait_end pairing
• Correct vercmp return-value documentation

🧠 Review effort: Lite

---

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

[Copilot]

🟡 Changes recommended

The WSREP wrapper signature mismatch can break dynamic-plugin compilation, and documentation hierarchy and formatting fixes remain.

2 open findings

• Align wsrep_get_domain_id wrapper signature with service API · New
• Wrap long Doxygen line to meet 80-character limit · New

11 resolved since last review

• Use wsrep_thd_set_wsrep_PA_unsafe_func in wrapper
• Use wsrep_report_bf_lock_wait_func in wrapper
• Document the accessor's integer log warning level
• Correct daemon plugin group description
• Fix misspelling of whatsoever
• Fix misspelling of array
• Fix misspelling of defaulted
• Fix misspelling of facilitate
• Fix misspelling of declaration
• Fix misspelling of successful
• Fix misspelling of exported

🧠 Review effort: Lite