Add Doxygen comments for lwp shared memory APIs #10900
Conversation
|
|
|
👋 感谢您对 RT-Thread 的贡献！Thank you for your contribution to RT-Thread! 为确保代码符合 RT-Thread 的编码规范，请在你的仓库中执行以下步骤运行代码格式化工作流（如果格式化CI运行失败）。 🛠 操作步骤 | Steps
完成后，提交将自动更新至 如有问题欢迎联系我们，再次感谢您的贡献！💐 |
github-actions
bot
added
RT-Smart
📌 Code Review Assignment🏷️ Tag: componentsReviewers: Maihuanyi Changed Files (Click to expand)
🏷️ Tag: components_lwpReviewers: xu18838022837 Changed Files (Click to expand)
📊 Current Review Status (Last Updated: 2025-11-07 10:36 CST)
📝 Review Instructions
|
|
您好，来信已收到！
|
There was a problem hiding this comment.
Pull Request Overview
This PR adds comprehensive Doxygen-style documentation comments to the LWP (Light Weight Process) shared memory management APIs in RT-Thread. The changes improve code maintainability by documenting the purpose, parameters, and return values of public functions and data structures.
Key Changes
- Added detailed Doxygen documentation for the
lwp_shm_structcontrol block - Documented all public shared memory APIs (
lwp_shmget,lwp_shmrm,lwp_shmat,lwp_shmdt,lwp_shminfo,list_shm) - Documented reference counting functions (
lwp_shm_ref_inc,lwp_shm_ref_dec)
| /** | ||
| * @brief Print information of all shared memory segments. | ||
| * | ||
| * This function prints the key, physical address, size and id of each | ||
| * shared memory segment to the console. It is exported as the Finsh/Msh | ||
| * command @c list_shm for debugging and inspection. | ||
| */ |
There was a problem hiding this comment.
[Documentation/文档]: The documentation mentions the function is 'exported as the Finsh/Msh command', but there is no corresponding export macro visible in this diff. Please verify that the MSH_CMD_EXPORT or FINSH_FUNCTION_EXPORT macro exists for this function, or update the documentation to reflect the actual export mechanism.
English: The documentation claims this function is exported as a Finsh/Msh command, but no export macro is shown in the changes. Either the documentation should clarify where/how the export happens, or verify the export macro exists elsewhere in the file.
中文: 文档声明此函数作为 Finsh/Msh 命令导出，但改动中未显示导出宏。文档应该说明导出在何处/如何发生，或验证导出宏在文件其他位置存在。
| int ref; | ||
| size_t key; | ||
| struct rt_mem_obj mem_obj; /**< Memory object interface used by aspace/varea */ | ||
| size_t addr; /**< Physical address of the shared memory; used as next pointer in the free list when unused */ |
There was a problem hiding this comment.
[Documentation/文档]: The documentation for the addr field describes it as 'Physical address' and also mentions it is 'used as next pointer in the free list when unused'. This dual-purpose nature could be more clearly documented by specifying that the type is size_t (not a pointer type). Consider clarifying whether this holds a physical address value or should be cast when used as a linked list pointer.
English: The addr field documentation indicates it serves two purposes: storing a physical address when in use, and acting as a next pointer in the free list when unused. Since the type is size_t rather than a pointer type, the documentation should clarify how the dual usage is implemented (e.g., 'stored as integer value and cast to pointer for free list operations').
中文: addr 字段文档表明它有两个用途：使用时存储物理地址，未使用时作为空闲链表的 next 指针。由于类型是 size_t 而非指针类型，文档应该说明如何实现双重用途（例如，'存储为整数值，在空闲链表操作时强制转换为指针'）。
| size_t addr; /**< Physical address of the shared memory; used as next pointer in the free list when unused */ | |
| size_t addr; /**< Physical address of the shared memory when in use; when unused, stores the index of the next free item in the free list as an integer value (size_t). Interpretation depends on context; no pointer type is used, so casting may be required for free list operations. */ |
Add Doxygen-style comments for the lwp shared memory public APIs in components/lwp/lwp_shm.c and the related control structure. This change is documentation-only and does not modify any runtime behavior or logic. Signed-off-by: ibvqeibob <2601187225@qq.com>
ibvqeibob
force-pushed
the
feature/add-doxygen-lwp
branch
from
e688e35 to
efdfec4
Compare
|
我看了一下 Static code analysis 的日志，报错来自 |
3 participants
拉取/合并请求描述：(PR description)
[
为什么提交这份PR (why to submit this PR)
components/lwp/lwp_shm.c中的 lwp 共享内存相关接口补充 Doxygen 注释，方便后续自动生成文档，也方便新同学和使用者理解这些 API 的作用和用法。你的解决方案是什么 (what is your solution)
lwp_shmgetlwp_shmrmlwp_shmatlwp_shm_ref_inclwp_shm_ref_declwp_shmdtlwp_shminfolist_shmstruct lwp_shm_struct添加结构体简介以及各字段的说明。请提供验证的bsp和config (provide the config and bsp)
BSP:
.config:
.config配置。action:
]
当前拉取/合并请求的状态 Intent for your PR
必须选择一项 Choose one (Mandatory):
代码质量 Code Quality：
我在这个拉取/合并请求中已经考虑了 As part of this pull request, I've considered the following:
#if 0代码，不包含已经被注释了的代码 All redundant code is removed and cleaned up