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>
Chen Wang