Composer包文档需从composer.json生成起同步推进，README必须含定义、安装（composer require首行）、可运行示例、PHP版本与限制；API文档须标注参数约束、异常类型及典型失败场景；CHANGELOG需用✅/⚠️/❌标识变更性质并提供迁移路径；文档应通过phpdocumentor生成HTML并配置extra.docs字段。
Composer 包的文档不是“写完再补”，而是从 composer.json 生成那一刻起就该同步推进的事——没文档的包，等于没 API；没示例的 README，等于没入口。
README.md 必须包含这四块，缺一不可
用户 clone 下来第一眼只看 README，它得在 10 秒内回答四个问题：这是什么、怎么装、怎么用、出了问题找谁。常见错误是把 README 写成项目日记或技术博客摘要。
- 开头用一句话定义包角色，比如：“
easy-utils是一个零依赖的 PHP 工具函数集合，提供字符串/数组/日期的常用操作封装” -
composer require命令必须放在安装说明第一行，不加解释、不换行、不缩进 - 基础使用示例必须可复制粘贴运行，比如：
$str = EasyUtils\Str::slug('Hello World');，而不是“调用 slug 方法即可” - 末尾明确标注支持的 PHP 版本（如
PHP >=7.4）和已知限制（如“不支持 HHVM”），避免用户白装
API 文档不能靠 phpdoc 自动解析就完事
PSR-5（PHPDoc 标准）只是基础，真正影响使用者体验的是参数边界、返回值异常、调用上下文。很多包的 @param 写 string $input，但实际只接受非空、UTF-8 编码、不含控制字符的字符串。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 对易出错参数加「约束说明」，比如：
@param non-empty-string $path或 “仅接受 Unix 风格路径，Windows 反斜杠需提前转换” - 每个公共方法必须注明是否
throws异常，以及抛出什么类型（InvalidArgumentException还是自定义EasyUtilsException） - 避免写“详见源码”，而要给出典型失败场景，比如：
Str::parseJson()在 JSON 深度 > 512 时会触发RecursionError
CHANGELOG.md 不是版本日志，是升级决策依据
用户升级前不会读完整 changelog，只会扫一眼“有没有 break change”和“值不值得升”。把 v2.0.0 的破坏性变更藏在第 17 行，等于没写。
- 每版开头用 ✅ / ⚠️ / ❌ 标识变更性质：
⚠️ BREAKING: Str::truncate() 第二个参数默认值从 100 改为 50 - 对兼容性调整给出迁移路径，比如：
旧写法：Str::camel('foo_bar') → 新写法：Str::toCamel('foo_bar') - 不写“优化性能”这种虚话，改写成具体数字：
Arr::flatten() 平均耗时从 0.8ms 降至 0.12ms（10k 元素数组）
vendor 目录下不放文档，但 docs/ 目录必须有结构化输出
很多人把 Markdown 文件丢进 docs/ 就以为完成了文档建设，结果用户 require 包后根本看不到。真正的文档交付链路是：源码注释 → phpdocumentor 解析 → 生成静态 HTML → 发布到 GitHub Pages 或 Read the Docs。
- 所有公开类/方法的
/** */注释必须符合 PSR-19（PHPDoc 扩展规范），否则解析器无法识别@throws或@see - CI 流程中加入
phpdoc -d src/ -t docs/api/，每次 push 自动生成最新 API 页面 - 在
composer.json的extra字段声明文档地址："docs": "https://yourname.github.io/easy-utils/api"，方便 IDE 和 Packagist 抓取
最难的不是写多少字，而是判断哪些信息必须前置、哪些可以折叠、哪些压根不该出现——比如内部使用的 trait、未导出的 helper 函数，永远别放进公开文档。
