# 源码与说明

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

```text
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`。

## 函数说明

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

```markdown
# 登录

## manage.account.login

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

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

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

## 调用流程

```sh
dever inspect . --links
dever inspect . --links --check
```

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

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

## 修改与阅读

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

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

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