从 Definitions 生成 API 的文档

[LelouchHe]

你在什么场景下需要该功能？

我现在正在做 xmake 的 lua-ls 的 addon,给所有的 xmake.lua 中的 api 提供 definitions 文件

repo: https://github.com/LelouchHe/xmake-luals-addon

个人感觉如果 API 的文档能把 definitions 和此处的 doc 结合起来,会更好,这样让二者是同步的

描述可能的解决方案

有几个可能的实现:

1. api 的类型定义可以从 definitions 中生成,而解释说明可以从 md 里来
   • 优点: 解释说明在 md 里写会比较好看
   • 缺点: 需要工具把二者整合
2. 把解释说明也放在 definitions 文件里,而 api 的文档直接从里面生成 md 或 html
   • 优点: 文档和 definitions 可以完全同步
   • 缺点: 注释里写 md 虽然可以,但感觉不是很直接

描述你认为的候选方案

No response

其他信息

我本人不是特别熟悉 lua 的文档生成,不知道这样做是否可行?

目前 addon 的内容生成是先通过抓取 md 的内容,然后解析

但从抓取的结果来看,有很多信息丢失,或者格式不统一,导致需要很多手工修改,甚至直接从头开始写

这样的话,如果 api 进行变动,没有很好的办法同步更新 definition

[waruqi]

api 的类型定义可以从 definitions 中生成,而解释说明可以从 md 里来

这样有点耦合两种工具，文档维护稍微不注意，就可能 break 两边的解析同步。。

把解释说明也放在 definitions 文件里,而 api 的文档直接从里面生成 md 或 html

暂时不打算动文档整体架构，改动太大，而且还得处理中英文同步

[LelouchHe]

这样的话, addon 可能就是一次性的锁定在 2.7.7

如果有后续的大的改动,再进行更新

该 addon 已经上架 LuaLS addon manager

[waruqi]

通常描述域 api 一般不会大改，问题不大。。