mirror of
https://github.com/RT-Thread/rt-thread.git
synced 2025-10-19 12:14:30 +08:00
715334f357
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, theb084503b6dchange only modified the comments in src/cpu_up.c but not in src/cpu_mp.c, causing problems. Another drawback of theb084503b6dchange 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 <unicorn_wang@outlook.com>