RubyMine/LSP是否忽略YARD的@private、@!visibility private等私有设置?
核心结论
并非本地配置错误,当前主流Ruby IDE/LSP的默认解析逻辑,不会将你尝试使用的三类YARD标注直接等同于“需从自动补全列表移除的公共方法”——这类标注的原生设计目标是服务于YARD文档生成,而非IDE的语义解析规则。
标注失效的根本原因
- 标注设计用途与IDE解析逻辑存在本质错位
@!visibility private:是YARD提供的文档级可见性标记,作用是在生成的HTML文档中将方法归入私有分组,没有任何语法层面的实际效力,也从未被设计为可以替代Ruby代码中的private关键字。主流IDE判断方法可见性的第一优先级,永远是代码AST解析出的实际定义上下文(比如方法是否定义在private代码块、是否通过private :method语法标记),文档注释中的元数据优先级极低。@private:是YARD内置的文档过滤标记,作用是让生成的公开文档完全跳过对应方法,本身不携带任何可见性语义,没有IDE会将这个标记与补全列表隐藏逻辑绑定。@api private:是社区通用的“非稳定内部API”标记,设计用途是提示下游维护者不要依赖这类方法,目前没有任何IDE默认实现了“检测到该标记即从补全列表完全移除”的逻辑。
- 各受影响环境的实际解析行为
- RubyMine 2021.1:完全基于代码AST的实际可见性判定方法归属,不读取YARD的可见性标注。哪怕给公共方法添加全部三类私有标记,只要方法没有在代码层面被标记为私有,就一定会出现在自动补全列表中。该版本仅能识别
@api private标记,将这类方法的补全优先级降到最低,而非完全隐藏。 - Solargraph(Emacs/LSP、VS Code Ruby插件的通用后端):默认遵循“代码实际可见性优先”的解析规则,YARD的可见性标注仅作为文档弹窗的补充说明,不会覆盖代码层面的可见性判断,自然不会触发补全列表的过滤逻辑。
- RubyMine 2021.1:完全基于代码AST的实际可见性判定方法归属,不读取YARD的可见性标注。哪怕给公共方法添加全部三类私有标记,只要方法没有在代码层面被标记为私有,就一定会出现在自动补全列表中。该版本仅能识别
不破坏向后兼容性的落地方案
所有方案均不修改方法的实际调用权限,完全兼容老用户的直接调用逻辑:
- Solargraph环境适配:
- 保留方法上的
@!visibility private标准标注 - 在项目根目录的
.solargraph.yml配置中开启YARD可见性覆盖规则,让解析器优先读取标注的私有可见性,将对应方法从公共补全候选列表中移除,仅在用户主动查询私有方法时才会展示。
- 保留方法上的
- RubyMine 2021.1环境适配:
- 给方法补充
@api private标注 - 在设置中开启「Editor > General > Code Completion > Show non-API members last」选项,这类方法不会出现在默认补全的前置候选中,需要用户主动触发高级补全才会显示,不会干扰日常使用体验。
- 给方法补充
- 跨IDE通用兼容提示:不要使用
@private标记作为可见性声明,统一使用@!visibility private作为标准私有可见性标注,该标签是目前所有主流Ruby LSP/IDE在实现可见性解析时优先兼容的YARD标准。
补充说明:VS Code官方维护的Ruby LSP已经实现默认规则,检测到方法带有
@api private标记时,会自动将其从公共补全列表中过滤,该环境下仅需保留@api private标注即可达到预期效果,无需额外配置。
内容的提问来源于stack exchange,提问作者Nikita Fedyashev
相关产品推荐
相关产品推荐

