You need to enable JavaScript to run this app. RubyMine/LSP是否忽略YARD的@private、@!visibility private等私有设置?
优惠活动
大模型
产品
解决方案
定价
更多

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的可见性标注仅作为文档弹窗的补充说明,不会覆盖代码层面的可见性判断,自然不会触发补全列表的过滤逻辑。
不破坏向后兼容性的落地方案

所有方案均不修改方法的实际调用权限,完全兼容老用户的直接调用逻辑:

  • 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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.25 08:45:00