MDEV-39718: Produce Markdown plugin API documentation

[gkodinov]

Implemented a cmake utility macro to generate markdown documentation for the plugin API headers.
Fixed some doxygen comment mistakes in these.

[gemini-code-assist]

Code Review

This pull request introduces a new CMake utility to generate plugin API documentation using Doxygen and Moxygen, along with various documentation formatting improvements in header files to ensure proper rendering. The review identifies a critical bug in the CMake macro where the first source file is inadvertently removed from the list, causing incomplete documentation. Additionally, the feedback suggests using functions instead of macros for better encapsulation, adopting more idiomatic boolean options in CMake, and defaulting the documentation generation to off to avoid build-time dependency issues in environments lacking the required tools.

[gemini-code-assist]

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})

[gemini-code-assist]

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)

[gemini-code-assist]

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)

[gemini-code-assist]

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

ENDFUNCTION()