Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Feature] [doxygen] [audio] A plan to achieve audio components doxygen comments #10046

Open
1078249029 opened this issue Feb 27, 2025 · 9 comments
Assignees
Labels
Doc This PR/issue related with documents testcase

Comments

@1078249029
Copy link
Contributor

1078249029 commented Feb 27, 2025

Describe problem solved by the proposed feature

实现audio components的注释

Describe your preferred solution

我打算先把注释写了然后实现utest框架,以后补充components/drivers下的注释都按这个顺序来
目录的group结构方面我打算规划如下:

  • Aduio
    • Audio 相关的宏,由于宏类似于AUDIO_SAMP_RATExxK或者AUDIO_DSPxx,因此这里需要放几个同级目录来管理这些宏
    • Audio 相关的函数,除了audio pipe相关的都放这里
  • Audio Pipe
    • audio pipe相关的函数
      由于audio pipe宏不是很多,这里就直接放到audio pipe group下面

有的函数写的不好的地方我会在写好注释后另提pr修改,也算梳理模块了

各位觉得怎么样?

Describe possible alternatives

No response

@supperthomas
Copy link
Member

很好,有计划在什么平台验证吗?

@1078249029
Copy link
Contributor Author

有生成doxygen的脚本,我这里可以在线预览

@unicornx
Copy link
Contributor

Q1:对于 audio,我看 markdown 部分是缺失的,是否这次会补上?一个可以参考的网上文章 https://zhuanlan.zhihu.com/p/344383184

Q2:对于 audio 框架,我有个疑问,就是 audio pipe 部分是不是应该不属于 API 部分。因为从 driver 的 user 来看,API 仅仅是定义在 components/drivers/include/drivers/dev_audio.h 中的那些。
components/drivers/audio/dev_audio_pipe.h 中和 audio pipe 的相关部分是否都是仅在 audio 框架内部使用的?
对于 audio frameowork 的 client,也就是 audio 驱动, 应该不会直接用到 audio pipe 的接口吧,如果是这样,我觉得就 audio pipe 部分不应该属于 API,也不需要为它定义 group 从而展现在 html 中。当然代码注释依然可以加上,只是不进入 doxygen 的生成 html 部分。

Q3:有关 group 结构,从你的文字描述上看不太清楚,可以给个 tree 描述吗?类似:

group_A
|_group_B
  |_group_C

Q4:从你的规划上来看,似乎 Audio 下宏和函数还要定义 group? 没有看明白,感觉 group 的概念应该不会用来区分 函数和 宏吧

Q3 和 Q4 也可以提交一个 RFC 的 pr,直接看看代码就清楚了。

Q5:我建议的 pr 步骤如下:

  • 基于现有设计和代码 提 pr 修改文档,包括 markdown 的文字部分,API 的 doxygen 注释部分等
  • 如果觉得现有代码有问题,可以再提 pr 改代码,相应的提 pr 改文档。如果改动不大,代码和文档的改动可以一个 pr,否则建议分开。
  • 再提一个 pr 解决 utest。感觉这个需要设计好如何测试,是否可以引入 pesudo device 辅助测试 API。如果要引入 pesudo device,这个又是一个自动化测试的框架,可能需要在 utest 的 pr 前单独提 pr 来做。

其他未尽事宜,欢迎补充。

@unicornx unicornx added Doc This PR/issue related with documents testcase labels Feb 28, 2025
@1078249029
Copy link
Contributor Author

A1: markdown这部分我还在想,目前我认为最好的还是rtt的官方文档,结构和内容也很符合introduction,直接把文档搬过来也是不错的选择
A2: pipe都是在audio内部使用的。我以为需要补充并暴露audio组件所有非static符号的注释的,毕竟写的是文档,理应越全越好,使用的时候也只是查个api。如果需要写驱动可以参考例程或者别人的代码,多余的api直接当成手册了。按您这么说只暴露写驱动和应用层的api也没什么问题......而且风格与其他模块的注释是一样的。感觉挺两难的
A3:

Image

A4: group只区分不同种类的宏,Audio的采样率和码率等配置宏的选项太多了,用group会更规整一些

@unicornx
Copy link
Contributor

unicornx commented Feb 28, 2025

A2: pipe都是在audio内部使用的。我以为需要补充并暴露audio组件所有非static符号的注释的,毕竟写的是文档,理应越全越好,使用的时候也只是查个api。如果需要写驱动可以参考例程或者别人的代码,多余的api直接当成手册了。按您这么说只暴露写驱动和应用层的api也没什么问题......而且风格与其他模块的注释是一样的。感觉挺两难的 A3:

我觉得没什么两难的,“越全越好” 也不是原则,我们的原则就是 “html 上出现的是 API”。所以我觉得对于 components/drivers/audio/dev_audio_pipe.h 中的那些结构体和函数,如果不是开放给外部驱动使用的,就不要出现在 html 上。但是 pipe 相关的 .c 和 .h 中依然可以写注释。只要不要 addtogroup 啥的就不会出现在 html 上。所以我看你贴的图上的 Audio Pipe 那个部分是不是应该不出现?

A4: group只区分不同种类的宏,Audio的采样率和码率等配置宏的选项太多了,用group会更规整一些

我理解你这么做是因为看宏比较多,所以想分一下类,对吧。可以试试,你图片展示的是 treeview 的效果,右边页面上的效果又会是如何?如果你不想提 rfc pr ,其实也可以贴你的 github 开发仓库的 branch 上来,省的贴图。

@1078249029
Copy link
Contributor Author

我把markdown补完就提个rfc吧,但是没有合并到主线生成的文档的视觉效果能看到么?

@unicornx
Copy link
Contributor

我把markdown补完就提个rfc吧,但是没有合并到主线生成的文档的视觉效果能看到么?

只要能拿到你的 branch,我自己本地也能看

@supperthomas
Copy link
Member

我把markdown补完就提个rfc吧,但是没有合并到主线生成的文档的视觉效果能看到么?

可以的,提交PR的时候,会有个产出文件,打开即可看到效果。

@supperthomas
Copy link
Member

Image

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Doc This PR/issue related with documents testcase
Projects
None yet
Development

No branches or pull requests

3 participants