Skip to content

Commit 1034e5b

Browse files
unicornxRbb666
authored andcommitted
doxygen: fixed duplicated comments for scheduler APIs
Similar to PR #10674, `src/scheduler_mp.c` and `src/scheduler_up.c` also have similar issues. After investigation, we found: in commit 2c98ce4 "[HUST CSE][document] Fix some comments, invalid grouping commands and warnings in Doxygen." This patch excluded `src/scheduler_mp.c` and `src/scheduler_up.c` from the Doxygen build and include `documentation/doxygen/thread.h` (the new file path after adjustment is `documentation/0.doxygen/core/thread.h`), placing the Doxygen comments for some functions in this file. However, this approach has its problems: - The comments in `documentation/0.doxygen/core/thread.h` are separated from the source code, making them difficult to maintain. This also results in the comments for the newly added functions in `src/scheduler_mp.c` and `src/scheduler_up.c` not being updated in a timely manner and failing to be compiled into Doxygen (becoming HTML). - For the average programmer, it's unlikely that they'll consider the `documentation/0.doxygen/` directory for function declarations and comments, let alone the need to maintain the Doxygen comments in that directory. Currently, the header files under `documentation/0.doxygen/` should strictly be used only to define Doxygen groups and should not include Doxygen comments for the code itself. (Similar issues exist in documentation/0.doxygen/3.hardware.h and documentation/0.doxygen/core/systeminit.h, which require further cleanup.) The solution is similar to PR #10674, where only MP documentation is generated by default. For functions defined in MP but not in UP, we use the "@note" directive in the function's doxygen comment to indicate whether the function is supported in both UP and MP, or only in MP. After implementing this solution, the file `documentation/0.doxygen/core/thread.h` can be deleted. Signed-off-by: Chen Wang <[email protected]>
1 parent b525d2c commit 1034e5b

File tree

3 files changed

+99
-131
lines changed

3 files changed

+99
-131
lines changed

documentation/0.doxygen/core/thread.h

Lines changed: 0 additions & 89 deletions
This file was deleted.

0 commit comments

Comments
 (0)