ESLint 核心文档中关于作用域管理接口的注释清理建议

在ESLint项目的核心文档中，作用域管理器接口(Scope Manager Interface)部分存在一些带有"我希望..."字样的注释，这些注释看起来更像是开发者个人的工作笔记而非正式的文档内容。

这些注释出现在三个关键方法的描述中：

1. set方法：文档中有一个注释表达了开发者对改进该方法的期望
2. functionExpressionScope方法：包含了一个关于未来改进想法的备注
3. identifiers属性：同样存在一个开发者个人的工作笔记式注释

从技术角度来看，这类注释更适合出现在代码提交信息或内部开发讨论中，而不应该保留在面向用户的正式文档里。作为API文档，应该专注于清晰地描述当前接口的功能和行为，而不是开发者的未来计划或愿望。

这类注释最早可以追溯到2016年的一个提交，显然是在文档编写过程中留下的临时性笔记，但后来被意外保留了下来。在API文档中保留这类内容可能会给用户带来困惑，让他们误以为这是接口的某种特殊行为或限制。

对于开源项目的文档维护，建议：

• 保持文档内容与当前实现严格一致
• 开发者笔记和未来计划应该通过其他渠道记录
• 接口文档应该专注于"是什么"而非"可能会是什么"
• 定期审查文档，移除过时或不相关的内容

这个案例也提醒我们，在编写技术文档时需要区分开发过程中的临时笔记和最终面向用户的正式内容。良好的文档实践应该包括文档审查环节，确保只发布对用户有价值的信息。