16 Commits

Author	SHA1	Message	Date
Chen Wang	273185b45a	doxygen: fix two issues when building with doxygen 1.9.8 (#10768) ... * doxygen: remove @return command if function return void When doxygen is upgraded to v1.9.8 (on ubuntu 24.04), doxygen reports: "doxygen error: found documented return type for xxx that does not return anything" for those functions which return void but declare "@return" in doxygen comment. Solution: remove "@return" for those cases, and update guide document for how to write doxgen comment for functions. Signed-off-by: Chen Wang <unicorn_wang@outlook.com> * doxygen: fixed a minor typo for uart doc This error is found when building with doxygen 1.9.8, but not detecetd on 1.9.1. Signed-off-by: Chen Wang <unicorn_wang@outlook.com>	2025-10-10 10:05:06 +08:00
Chen Wang	1034e5b4fd	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 2c98ce4605 "[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 <unicorn_wang@outlook.com>	2025-09-09 18:20:41 +08:00
Chen Wang	3c046646cb	doxygen: promote object management to a separate page ... For "RT-Thread User Guide": Take the "RT-Thread Kernel Object Model" sub-section out of the "Kernel Basics" section and rename it to "Object Management". Correspondingly, rename the "Kernel Object Management" section in the "RT-Thread API Guide" to "Object Management". Signed-off-by: Chen Wang <unicorn_wang@outlook.com>	2025-07-22 18:07:17 +08:00
Chen Wang	2aebe694d9	doxygen: group name all in lowcase (part 2) (#10530) ... * doxygen: fs: unify groupname to lowercase Signed-off-by: Chen Wang <unicorn_wang@outlook.com> * doxygen: drivers: unify groupname to lowercase Signed-off-by: Chen Wang <unicorn_wang@outlook.com> * doxygen: signal: unify groupname to lowercase Signed-off-by: Chen Wang <unicorn_wang@outlook.com> --------- Signed-off-by: Chen Wang <unicorn_wang@outlook.com>	2025-07-22 13:59:25 +08:00
Chen Wang	8e9872a554	doxygen: group name all in lowcase ... This patch only updated the groups defined in documentation/0.doxygen. Other groups will be moved into documentation/0.doxygen and updated at that time. Signed-off-by: Chen Wang <unicorn_wang@outlook.com>	2025-06-25 14:02:28 +08:00
Chen Wang	e234cc8658	doxygen: change group_Device to group_device_driver ... The originally defined "group_Device" should actually be part of the device-driver component, so create a new "group_device_driver" and then rename "group_Device" to "group_device_driver". Signed-off-by: Chen Wang <unicorn_wang@outlook.com>	2025-05-29 13:47:46 +08:00
Chen Wang	55428e4393	doxygen: re-org module groups (#10197) ... Match the organization of modules (groups) with that of user guide. Preliminary arrangement. This patch is just a framework arrangement. Details need to be continued. P.S., in this patch, adding numerical prefixes to the files in documentation/0.doxygen is to meet the need of displaying sorting in HTML pages. Signed-off-by: Chen Wang <unicorn_wang@outlook.com>	2025-04-18 10:44:43 +08:00
Chen Wang	4ff1cfce64	doxygen: cleanup and re-org files ... This patch contains two small changes, mainly to prepare for the next step of organizing the modules framework. The first change: move the files related to doxygen examples to `documentation/0.doxygen/example/` The second change: delete `documentation/0.doxygen/mainpage.h`, which is the mainpage of the old page. Now the new mainpage is `documentation/INDEX.md`, so the duplicate can be deleted. Signed-off-by: Chen Wang <unicorn_wang@outlook.com>	2025-04-13 15:28:21 +08:00
Chen Wang	88607c1404	doxygen: fix wrong ref for group examples ... Fixes: 94afe6a4f1 ("doxygen: improve howto") Signed-off-by: Chen Wang <unicorn_wang@outlook.com>	2025-03-12 12:55:06 +08:00
Chen Wang	94afe6a4f1	doxygen: improve howto ... - Add description on how to group macros. - Add description for structs on how to write comments for members when the name of member is too. - Use @ref to link group instead of the html filenames. Signed-off-by: Chen Wang <unicorn_wang@outlook.com>	2025-03-10 10:08:48 +08:00
Chen Wang	3c8b23576f	doxygen: group examples in subpages ... Doxygen examples are grouped on different pages so that you can easily link to pages of related types in the documentation. For example, macro examples have their own page, and function examples have their own page, which correspond to their own code examples, such as "macro.h" or "function.h". Signed-off-by: Chen Wang <unicorn_wang@outlook.com>	2025-03-06 11:46:21 +08:00
wumingzi	600e4ab517	Add recommanded script and extension for writing doxygen comments on … (#10001) ... Add recommanded script and extension for writing doxygen comments on vscode Signed-off-by: 1078249029 <1078249029@qq.com>	2025-02-19 09:06:15 +08:00
Chen Wang	c40b79037c	doxygen: add prefix for groups (#9991) ... * doxygen: add prefix for groups Add "group_" prefix to doxygen group names. This makes it easier to grep with group name later. This patch only modifies the groups defined in the pathes of INPUT of documentation/Doxyfile: INPUT = . \ ../src \ ../include \ ../components/finsh \ ../components/drivers/include/drivers \ ../components/drivers/clk \ ../components/dfs/dfs_v2/src \ ../components/dfs/dfs_v2/include Other groups are not touched. Signed-off-by: Chen Wang <unicorn_wang@outlook.com> * ci: fixed error report when run file_check.py Such as: - "please delete extra space at the end of this line." - "the RT-Thread error code should return negative value. e.g. return -RT_ERROR" Signed-off-by: Chen Wang <unicorn_wang@outlook.com> --------- Signed-off-by: Chen Wang <unicorn_wang@outlook.com>	2025-02-15 12:15:19 +08:00
Chen Wang	f6f7d91a61	doxygen: add prefix for page name (#9989) ... Add prefix "page_" to the name of pages. Add this as a rule in guide of writing doxygen documents. Signed-off-by: Chen Wang <unicorn_wang@outlook.com>	2025-02-13 23:28:19 +08:00
Chen Wang	761bb89f27	doxygen: add documentation for doxygen ... Documentation is provided to clarify how to write doxygen documentation for RT-Thread. This document is also integrated as part of RT-Thread doxygen documentation. An example is also provided. The original README.md is removed and integrated into this document. Updated github actions for doxygen too. Signed-off-by: Chen Wang <unicorn_wang@outlook.com>	2025-02-11 17:09:44 +08:00
Chen Wang	40f3b6a569	doxygen: create framework to unify markdown and source code part (#9946) ... * doxygen: adjust documentation directory structure - Rename documentation/doxygen to documentation/0.doxygen and cleanup some unused files. - Add/rename folders for each sub sections, such as 1.introduction/...... Each sub section will be created as a subpage. - Generate initial Doxyfile, this Doxyfile will be used to unify doxygen generated API documents and those markdown files under documentation folder. This patch just add the default Doxyfile generated by running "doxygen -g". It is used as baseline to add more features/configurations. - Rename documentation/README.md to documentation/INDEX.md, and use it as mainpage. - Move 0.doxygen/readme.md to documentation/README.md. * doxygen: update configurations These configurations are from old documentation/doxygen/Doxyfile. Try best to compatible exixting design. * doxygen: add run script Add a script to automatic some operations. Updated the README.md. --------- Signed-off-by: Chen Wang <unicorn_wang@outlook.com> Co-authored-by: Supper Thomas <78900636@qq.com>	2025-01-26 11:44:39 +08:00