From aecd06f04c32fc10e0d406c0a2817440c4f5fb8d Mon Sep 17 00:00:00 2001
From: Georgi Kodinov <joro@mariadb.org>
Date: Fri, 29 May 2026 15:06:41 +0300
Subject: [PATCH] MDEV-39806: Add a per-push/per-pull-request checker for
 Markdown API docs

Create a GitHub action into the MariaDB server tree to build the Markdown
documentation using the cmake target provided by MDEV-39718.

This workflow generates API documentation for the plugin using a
Docker container packed with all the extra doxygen/moxygen tools.
Fixed some more doxygen problems.
Moved the repo to ghcr.io/mariadb/mariadb-doc-gen:latest.
---
 .github/workflows/generate-api-docs.yml   | 26 +++++++++++++++++++++++
 include/mysql/generate_plugin_api_docs.sh |  6 ++++++
 include/mysql/psi/psi.h                   |  5 ++---
 3 files changed, 34 insertions(+), 3 deletions(-)
 create mode 100644 .github/workflows/generate-api-docs.yml

diff --git a/.github/workflows/generate-api-docs.yml b/.github/workflows/generate-api-docs.yml
new file mode 100644
index 0000000000000..6ad538451b000
--- /dev/null
+++ b/.github/workflows/generate-api-docs.yml
@@ -0,0 +1,26 @@
+name: Generate Plugin API Docs
+
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request:
+    branches:
+      - 'main'
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/mariadb/mariadb-doc-gen:latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Generate documentation
+        shell: bash
+        run: |
+          set -euo pipefail
+          target_dir=$(pwd)/bld/docs/plugin-api
+          mkdir -p "$target_dir"
+          cd include/mysql
+          bash -x generate_plugin_api_docs.sh "$target_dir"
diff --git a/include/mysql/generate_plugin_api_docs.sh b/include/mysql/generate_plugin_api_docs.sh
index 5e4be538bb3fa..c11009d56a9ae 100644
--- a/include/mysql/generate_plugin_api_docs.sh
+++ b/include/mysql/generate_plugin_api_docs.sh
@@ -12,6 +12,8 @@
 # Note: target_dir is created if not present.
 # Note: requires at least moxygen 2.1.11
 
+set -euo pipefail
+
 # If no target_dir is specified, the current directory is used.
 if [ -n "$1" ]; then
     TARGET_DIR="$1"
@@ -29,6 +31,10 @@ rm -rf "$TARGET_DIR/xml"
 # Create the markdown output directory
 mkdir -p "$TARGET_DIR/md"
 
+echo "Doxygen version"
+doxygen --version
+echo "Moxygen version"
+moxygen --version
 # run doxygen to generate the plugin API documentation XML
 # Need to pass output directory so that XML docs get generated in it.
 # Need to EXCLUDE the output directory so that doxygen does not try to parse the generated XML and markdown files
diff --git a/include/mysql/psi/psi.h b/include/mysql/psi/psi.h
index 10f0937b66ed2..038893628d4f1 100644
--- a/include/mysql/psi/psi.h
+++ b/include/mysql/psi/psi.h
@@ -1544,7 +1544,6 @@ typedef void (*unbind_table_v1_t)
   Rebind a table handle to the current thread.
   This operation happens when a table from the open table cache
   is reused for a thread.
-  @param table the table to unbind
 */
 typedef PSI_table* (*rebind_table_v1_t)
   (PSI_table_share *share, const void *identity, PSI_table *table);
@@ -1552,7 +1551,6 @@ typedef PSI_table* (*rebind_table_v1_t)
 /**
   Close an instrumentation table handle.
   Note that the table handle is invalid after this call.
-  @param table the table handle to close
 */
 typedef void (*close_table_v1_t)(struct TABLE_SHARE *server_share,
                                  struct PSI_table *table);
@@ -1586,6 +1584,7 @@ typedef int (*spawn_thread_v1_t)(PSI_thread_key key,
   Create instrumentation for a thread.
   @param key the registered key
   @param identity an address typical of the thread
+  @param thread_id the id of the thread
   @return an instrumented thread
 */
 typedef struct PSI_thread* (*new_thread_v1_t)
@@ -2020,6 +2019,7 @@ typedef void (*end_stage_v1_t) (void);
   @param state data storage for the locker
   @param key the statement instrumentation key
   @param charset client character set
+  @param sp_share the share
   @return a statement locker, or NULL
 */
 typedef struct PSI_statement_locker* (*get_thread_statement_locker_v1_t)
@@ -2348,7 +2348,6 @@ typedef void (*set_socket_thread_owner_v1_t)(struct PSI_socket *socket);
 
 /**
   Get a prepare statement.
-  @param locker a statement locker for the running thread.
 */
 typedef PSI_prepared_stmt* (*create_prepared_stmt_v1_t)
   (void *identity, uint stmt_id, PSI_statement_locker *locker,