Skip to content

MDEV-39718: Produce Markdown plugin API documentation #5112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
gkodinov wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

MDEV-39718: Produce Markdown plugin API documentation #5112

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions cmake/plugin_api_docs.cmake
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Copyright (c) 2026, MariaDB Corporation
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; version 2 of the License.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA

SET(WITH_PLUGIN_API_DOCS yes CACHE STRING "Produce the API docs")
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The option WITH_PLUGIN_API_DOCS is defined as a STRING with a default of yes. It is more idiomatic in CMake to use the OPTION() command or SET(... CACHE BOOL ...) for boolean flags. Additionally, since this feature introduces new build-time dependencies (doxygen and moxygen), it should ideally default to OFF to avoid breaking existing build environments that lack these tools by default.

OPTION(WITH_PLUGIN_API_DOCS "Produce the API docs" OFF)


# Produce plugin API docs. The docs are generated as part of the build,
# but only if WITH_PLUGIN_API_DOCS is set to yes. The docs are generated
# using doxygen and moxygen, and are output to the api_docs directory
# in the build directory.
# First doxygen is called to produce XML output into api_docs/xml,
# and then moxygen is called to produce markdown output into api_docs/md out
# of the XML output.

# Call with a list of sources, e.g.
# PLUGIN_API_DOCS_GENERATE(foo.h bar.h)

MACRO (PLUGIN_API_DOCS_GENERATE)
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Using FUNCTION is preferred over MACRO in CMake to prevent internal variables (like SOURCES, ARG_UNPARSED_ARGUMENTS, and the DOXYGEN_* configuration variables) from leaking into the caller's scope. Since this logic defines a build target and sets local configuration, a function provides better encapsulation.

FUNCTION (PLUGIN_API_DOCS_GENERATE)

IF (NOT WITH_PLUGIN_API_DOCS)
RETURN()
ENDIF()
CMAKE_PARSE_ARGUMENTS(ARG
""
""
""
${ARGN}
)
SET(SOURCES ${ARG_UNPARSED_ARGUMENTS})
LIST(REMOVE_AT SOURCES 0)
Comment on lines +39 to +40
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

This line removes the first element from the SOURCES list. Based on the usage in include/CMakeLists.txt, where the macro is called with a list of header files, this will cause the first header (e.g., mysql/plugin.h) to be excluded from the generated documentation. If the intention was to handle a target name as the first argument, the macro signature and the call site should be updated accordingly; otherwise, this removal should be deleted.

  SET(SOURCES ${ARG_UNPARSED_ARGUMENTS})

MESSAGE(STATUS "Will generate plugin API docs")

FIND_PACKAGE(Doxygen REQUIRED)
FIND_PROGRAM(MOXYGEN_BIN moxygen REQUIRED)

FILE(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/api_docs)
FILE(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/api_docs/md)

SET(DOXYGEN_FILE_PATTERNS *.h)
SET(DOXYGEN_GENERATE_HTML NO)
SET(DOXYGEN_WARN_IF_UNDOCUMENTED NO)
SET(DOXYGEN_GENERATE_XML YES)
SET(DOXYGEN_INCLUDE_PATH ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR})
SET(DOXYGEN_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/api_docs)
SET(DOXYGEN_WARN_AS_ERROR YES)
SET(DOXYGEN_EXTRACT_ALL YES)
SET(DOXYGEN_QUIET YES)
SET(DOXYGEN_XML_PROGRAMLISTING YES)
doxygen_add_docs(plugin_api ${SOURCES} ALL USE_STAMP_FILE COMMENT "Generating plugin API XML docs with doxygen")
ADD_CUSTOM_COMMAND(TARGET plugin_api POST_BUILD
COMMAND ${MOXYGEN_BIN} --quiet
--source-root ${CMAKE_SOURCE_DIR}
${CMAKE_BINARY_DIR}/api_docs/xml
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/api_docs/md
BYPRODUCTS ${CMAKE_BINARY_DIR}/api_docs/md/api.md
COMMENT "Generating plugin API docs with moxygen"
)
ENDMACRO()
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Change to ENDFUNCTION() to match the suggested change from MACRO to FUNCTION.

ENDFUNCTION()

43 changes: 43 additions & 0 deletions include/CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,3 +121,46 @@ INSTALL_COMPAT_HEADER(mysql_version.h "
INSTALL_COMPAT_HEADER(mysql_com.h "
#include <mariadb_com.h>
")

SET(PLUGIN_API_HEADERS
mysql/plugin.h
mysql/plugin_audit.h
mysql/plugin_auth.h
mysql/plugin_data_type.h
mysql/plugin_encryption.h
mysql/plugin_ftparser.h
mysql/plugin_function.h
mysql/plugin_password_validation.h
)
SET(PLUGIN_SERVICE_HEADERS
mysql/service_base64.h
mysql/service_log_warnings.h
mysql/service_print_check_msg.h
mysql/service_thd_autoinc.h
mysql/service_thd_wait.h
mysql/service_debug_sync.h
mysql/service_logger.h
mysql/service_progress_report.h
mysql/service_thd_error_context.h
mysql/service_wsrep.h
mysql/service_encryption_scheme.h
mysql/service_md5.h
mysql/service_sha1.h
mysql/service_thd_mdl.h
mysql/services.h
mysql/service_encryption.h
mysql/service_my_crypt.h
mysql/service_sha2.h
mysql/service_thd_rnd.h
mysql/service_json.h
mysql/service_my_print_error.h
mysql/service_sql.h
mysql/service_thd_specifics.h
mysql/service_kill_statement.h
mysql/service_my_snprintf.h
mysql/service_thd_alloc.h
mysql/service_thd_timezone.h)

INCLUDE(${CMAKE_SOURCE_DIR}/cmake/plugin_api_docs.cmake)

PLUGIN_API_DOCS_GENERATE(${PLUGIN_API_HEADERS} ${PLUGIN_SERVICE_HEADERS})
4 changes: 2 additions & 2 deletions include/mysql/service_debug_sync.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,7 +223,7 @@

There are quite a few places in MySQL, where we use a synchronization
pattern like this:

@code
mysql_mutex_lock(&mutex);
thd->enter_cond(&condition_variable, &mutex, new_message);
#if defined(ENABLE_DEBUG_SYNC)
Expand All @@ -233,7 +233,7 @@
while (!thd->killed && !end_of_wait_condition)
mysql_cond_wait(&condition_variable, &mutex);
thd->exit_cond(old_message);

@endcode
Here some explanations:

thd->enter_cond() is used to register the condition variable and the
Expand Down
2 changes: 1 addition & 1 deletion include/mysql/service_logger.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@

Finally the log should be closed with logger_close().

@notes:
@note:
Implementation checks the size of the log file before it starts new
printf into it. So the size of the file gets over the limit when it rotates.

Expand Down
19 changes: 10 additions & 9 deletions include/mysql/service_my_snprintf.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,19 +39,21 @@

@note
The syntax of a format string is generally the same:
@verbatim
%[<flag>][<length>][.<precision>][<size modifier>]<format>[<format extension>]
where everything but the <format> is optional.
@endverbatim
where everything but the \<format\> is optional.

Two one-character <flags> are recognized:
Two one-character \<flags\> are recognized:
'0' has the standard zero-padding semantics;
'-' is parsed, but silently ignored;

Both <length> and <precision> are the same as in the standard.
Both \<length\> and \<precision\> are the same as in the standard.
They can be specified as integers, or as '*' to consume an int argument.

<size modifier> can be 'l', 'll', or 'z'.
\<size modifier\> can be 'l', 'll', or 'z'.

Supported <format>s are 's' (null pointer is accepted, printed as "(null)"),
Supported \<format\>s are 's' (null pointer is accepted, printed as "(null)"),
'c', 'd', 'i', 'u', 'x', 'X', 'o', 'p' (works as "0x%x"), 'f', and 'g'.

The '$n' syntax for positional arguments is supported.
Expand All @@ -60,12 +62,11 @@

Format 'sQ'
quotes the string with '`' (backtick)s similar to "`%s`",
but also "escapes" existing '`'s in the string to '``' as in SQL ''''.

but also "escapes" existing '`'s in the string to '\`\`' as in SQL ''''.
Format 'sB'
treats the argument as a byte sequence. It reads and prints exactly
<precision> bytes without terminating on any '\0's in the sequence.
The default <precision> when it's unspecified is not defined.
\<precision\> bytes without terminating on any '\0's in the sequence.
The default \<precision\> when it's unspecified is not defined.

Format 'sT'
replaces the end of the printed string with "..." if it was truncated.
Expand Down
2 changes: 1 addition & 1 deletion include/mysql/service_progress_report.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,14 +55,14 @@ extern struct progress_report_service_st {

#else

void thd_progress_init(MYSQL_THD thd, unsigned int max_stage);
/**
Report progress for long running operations

@param thd User thread connection handle
@param progress Where we are now
@param max_progress Progress will continue up to this
*/
void thd_progress_init(MYSQL_THD thd, unsigned int max_stage);
void thd_progress_report(MYSQL_THD thd,
unsigned long long progress,
unsigned long long max_progress);
Expand Down
6 changes: 3 additions & 3 deletions include/mysql/service_thd_autoinc.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,9 @@ extern struct thd_autoinc_service_st {
#else
/**
Return autoincrement system variables
@param IN thd user thread connection handle
@param OUT off the value of @@SESSION.auto_increment_offset
@param OUT inc the value of @@SESSION.auto_increment_increment
@param[in] thd user thread connection handle
@param[out] off the value of @@SESSION.auto_increment_offset
@param[out] inc the value of @@SESSION.auto_increment_increment
*/
void thd_get_autoinc(const MYSQL_THD thd,
unsigned long* off, unsigned long* inc);
Expand Down
7 changes: 4 additions & 3 deletions include/mysql/service_thd_rnd.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,10 @@ double thd_rnd(MYSQL_THD thd);
/**
Generate string of printable random characters of requested length.

@param to[out] Buffer for generation; must be at least length+1 bytes
long; result string is always null-terminated
@param length[in] How many random characters to put in buffer
@param thd User thread connection handle
@param[out] to Buffer for generation; must be at least length+1 bytes
long; result string is always null-terminated
@param[in] length How many random characters to put in buffer
*/
void thd_create_random_password(MYSQL_THD thd, char *to, size_t length);

Expand Down
Loading