The current test environment is mainly based on Ubuntu
22.04 LTS and doxygen version is 1.9.1.
But when we switch to Ubuntu 24.04, the default Doxygen
version on Ubuntu 24.04 is 1.9.8.
The supported configuration and layout file formats
differ from those in 1.9.1 (Ubuntu 22.04).
In particular, the layout XML file format of 1.9.8 is
incompatible with the older format(1.9.1). Therefore,
to support Doxygen on Ubuntu 24.04, we need to load
different configuration and layout files. (The layout
file is specified using the LAYOUT_FILE parameter in
the configuration file.)
Solution: Provide corresponding configuration and layout
files for different Doxygen versions, distinguished by
the Doxygen version number.
Currently, only Doxygen versions 1.9.1 and above are supported.
If the doxygen version is >= 1.9.1 but < 1.9.8, the 1.9.1
configuration and layout are used by default. If the doxygen
version is >= 1.9.8, the 1.9.8 configuration and layout are used.
Only 1.9.1 and 1.9.8 have been tested, as these are the
default doxygen versions on Ubuntu 22.04 LTS and Ubuntu
24.04. Other versions have not been tested yet. If
necessary, we will change the configuration based on
the same approach in the future.
Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
* 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>
Many modules' utests currently don't support enabling all
tests at once. Furthermore, some modules' tests are complex,
for example due to their numerous dependencies on other
modules. This makes it nearly impossible to enable all
tests with a single global switch. Consequently, the
previously defined `RT_UTEST_USING_ALL_CASES` has lost
its original meaning.
We recommend deprecating this configuration switch. If a
module needs to enable a group of functional tests through
its own configuration, this local enable all switch should
be implemented by the module itself, and a global RTT enable
switch will no longer be provided.
If such a requirement arises in the future, we recommend
careful design, especially considering how to ensure that
turning on a single switch enables all dependencies for
all involved modules for ease of use.
Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
More details see PR #10681.
As utest cases are currently moving out of `examples/utest/testcases`
into their own module directories, the naming rule needs to change
accordingly.
Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
The introduction to Env under the documentation
section of the RTT source code repository is
outdated and unmaintained. We recommend moving the Env
documentation to https://github.com/RT-Thread/env/
for self-maintenance.
Solution:
Direct users to the latest README at https://github.com/RT-Thread/env/.
The Env content under the documentation section of RTT
will not be deleted for now, but will be marked as "outdated".
Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
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>
Refer to the issue described in PR #10599. This was a
temporary fix at that time.
After further research, we discovered that this issue
can be addressed using the "@cond" command supported
by Doxygen.
Since we currently do not intend to generate two sets
of documentation for UP and MP when generating Doxygen
documentation, the current solution is to generate only
MP documentation by default. For functions defined in
MP but not in UP, we will use the "@note" command in
the function's Doxygen comment to indicate whether the
function supports both UP and MP, or only MP.
Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
The code formatting in the Object Management Markdown document
is misaligned. This issue can be fixed by replacing tabs with spaces.
Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
After "utest: re-org utest framework (initial version)" (PR #10534)
was merged, adding a document to introduce how to add utest-cases
for your module.
Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
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>
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>
In line with the layout of the source code, the
Device-Driver submodule should belong to components.
The doxygen Module part has been adjusted. This commit
modifies the markdown document part and moves the
device-driver pages under to components.
Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
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>
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>
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>
Move the introduction of function parameters in markdown to
source code comments, because this part of the content is
completely repeated. We only need to keep and maintain the
comments in the code. The detailed explanation of the API
in markdown can directly refer to the comments in the code.
Try not to directly copy the definition of the structure
in the markdown document, because this part of the content
may change with the upgrade of the code. Therefore, when
the structure definition is involved in markdown, try to
indicate that it is just a code snippet. The specific
definition is still directly quoted from the source code
and the source code comments.
It is very convenient to quote structures and functions
in markdown. Just use "`" to enclose the structure name
or function name, and the generated html is a link to
its definition.
According to this principle, this patch only modifies
the documents and code comments of the kernel object model.
Other modules will be modified one by one in separate
patches later.
Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
- 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>
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>
Added comments for data structure and rt_audio_ops in dev_audio.h.
Enriched comments for macro group. Moved and renamed folder audio.
Signed-off-by: 1078249029 <1078249029@qq.com>
Organize the document content of the "Kerenl Basics" section.
This PR does not make substantial changes to the text content,
but only makes some optimizations and adjustments to the
document formatting, including:
- Enclose the function name and variable name in "`", so that
the HTML rendering will use different fonts to distinguish
them from the text part.
- Add blank lines between paragraphs, otherwise the HTML
rendering will merge the paragraphs without blank lines
into one paragraph.
- Use "@ref" to reference the page of the corresponding
chapter, such as the reference to page_thread_management
at the end of the "Thread Scheduling" chapter.
- For tables in markdown, try to align the columns in the
text to beautify the reading experience.
Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
The original directory structure was too flat and
inconvenient to view.
The directory is now reorganized according to the
first-level chapters, and some sub-chapters are
moved to the second-level directory.
Note: documentation/env is not moved to
documentation/4.tool because there are too many
external places that reference this path,
especially in bsp, so this directory path remains
as it is.
Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
Previously, you had to enter the documentation directory
before executing the run.sh script, which was not very
convenient during development, especially when you needed
to execute other commands in the source code root directory
at the same time, such as git commands.
Now you can directly run script in the source code root
directory as below:
```shell
$ cd $RTT
$ ./documentation/run.sh
```
No need to switch the working path any more after entering
the source code root directory.
Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
Github CI doc_doxygen is very strict in checking the
build results, and will output failure even if there
are warnings.
In order to match CI's checks, local build scripts
are also checked more strictly to detect potential
errors and even warnings as early as possible.
Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
* 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>
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>
Accroding to #9947 and #9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations.
- rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies.
- clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify.
- clk_release implements may be incomplete, so I just marked in comment.
Signed-off-by: 1078249029 <1078249029@qq.com>
* 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>
kservice.c:474: warning: The following parameter of rt_backtrace_to_buffer(rt_thread_t thread, struct rt_hw_backtrace_frame *frame, long skip, rt_ubase_t *buffer, long buflen) is not documented:
parameter 'thread'
kernel.h:157: warning: unable to resolve reference to '_rt_errno' for \ref command
Signed-off-by: supperthomas <78900636@qq.com>
