core/DOCUMENTATION.md

源码与说明

.dever 放代码，每个领域使用以下阅读入口：

module/manage/account/
├── README.md
├── doc/
│   ├── session.md
│   └── members.md
├── app/
│   ├── session.dever
│   └── members.dever
├── domain.dever
├── model.dever
└── link.md

README 用一段话介绍职责，并链接主题说明。doc 按功能组织；业务角色只创建实际需要的文件，小领域可以使用 app.dever。

函数说明

二级标题写完整符号名，正文说明代码不容易表达的业务含义：

# 登录

## manage.account.login

校验登录名和密码，成功后创建会话并设置 Cookie。凭据错误返回未授权。

• 简单函数通常一两句即可；复杂功能再补规则、失败条件和副作用。
• 参数含义不清楚时解释参数，不重复列出已展示的类型和签名。
• 不写“操作参数”“业务值”等占位文字，不把同一段介绍复制给每个函数。
• 一个逻辑函数只写一处说明，多分句共用。类型也可用完整符号名绑定说明。
• 调用方、行号和调用关系由工具读取，不手工维护。

不确定符号名时执行 dever inspect . --json。说明标题失效或重复时，检查器会报错；文字是否符合实现仍须对照源码。

调用流程

dever inspect . --links
dever inspect . --links --check

第一条命令生成各领域的 link.md，第二条检查是否过期。流程按源码求值顺序展示入口、分支、调用和任务调度，点击节点可打开源码。

图展示代码可能执行的路径，不是一次请求的运行记录。Port 的实际 Adapter 由配置选择。完整调用关系保留在 link 中，README 和 doc 不再复制。

修改与阅读

先读领域 README、相关主题和调用流程，再读源码。修改实现时同步受影响的说明与测试，重新生成调用图。

dever fmt . --check
dever check .
dever test . --filter manage.account
dever inspect . --links
dever inspect . --links --check

VS Code 插件可在悬浮中显示签名、说明和调用摘要，并跳转源码及上下游调用，见 插件说明。源码和说明保存后刷新索引，不需要在 Dever 源码里加说明注释。