doxygen: fix build error

fixed: b084503b6d "[kernel] add UP scheduler critical switch flag."

After this commit, doxygen build with warning:
include/rtthread.h:658: warning: argument 'lock' from the argument list of rt_spin_unlock has multiple @param documentation sections
include/rtthread.h:660: warning: argument 'lock' from the argument list of rt_spin_unlock_irqrestore has multiple @param documentation sections
include/rtthread.h:660: warning: argument 'level' from the argument list of rt_spin_unlock_irqrestore has multiple @param documentation sections

Rootcasue analysis:
src/cpu_up.c and src/cpu_mp.c define two identical functions.
Because the INPUT parameter in the documentation/Doxyfile currently
compiles all source files under ./src, i.e both of them, Doxygen
automatically merges the Doxygen comments for identically named
functions if it finds the content of doxygen comments different,
resulting in multiple @param.

Previously, the API comments in both files were identical, so there
was no problem. However, the b084503b6d change only modified the
comments in src/cpu_up.c but not in src/cpu_mp.c, causing problems.

Another drawback of the b084503b6d change is that Doxygen recommends
a single line for the @brief; multiple lines are not recommended.

Solution:
Given the requirement for a single line for the @brief, this issue
is relatively simple to resolve: simply list the extra content as @note.

Regarding the warning: A perfect solution has not yet been found.
One possible approach is to write a single Doxygen comment for a kernel
API with two implementations. This approach involves writing Doxygen
comments in only one file, such as src/cpu_up.c , while omitting them
in src/cpu_mp.c .

Another solution is to add API comments to include/rtthread.h , but the
RT-Thread include/rtthread.h file is already quite large, and adding
comments there would be even more cumbersome.

A temporary solution currently in use is to ensure that the Doxygen
comments for the same API are identical in both src/cpu_up.c and
src/cpu_mp.c . This ensures that Doxygen compilation does not
generate warnings, and the files are automatically merged into a
single file in the HTML document.

Signed-off-by: Chen Wang <[email protected]>

0 files changed, 0 insertions, 0 deletions