search

Shopify / ruby-lsp

An opinionated language server for Ruby
https://shopify.github.io/ruby-lsp/
MIT License
1.55k stars 148 forks source link

Support YARD directive comments #2181

Closed erickguan closed 3 months ago

erickguan commented 3 months ago

I have checked that this feature is not already implemented

Use case

This is a feature request to improve Hover.

I would expect that I can see YARD formatted documentation about a function method in a class. This is particularly useful when I create ruby methods through metaprogramming. Currently, hovering on a method that is created dynamically would not show any information.

Code example:

# @!method foo(name, opts = {})
create_a_foo_method

As a side, Solargraph supports parsing YARD directives. And solargraph VS Code plugin shows defined function upon hovering.

Description

RubyLSP should parse YARD directives when parsing code documents.

Implementation

No response

vinistock commented 3 months ago

Thank you for the feature suggestion.

However, we will not add support for YARD annotations. There are multiple reasons for that

  1. We try to keep the Ruby LSP's concerns related only to Ruby itself. YARD is a separate gem and not every Ruby developer uses it
  2. When it comes to adding type annotations, a complete gradual type system like Sorbet or Steep yields significantly better results. They provide the ability to narrow types, widen types, use generics, interfaces, etc - things that are not possible to do with YARD annotations
  3. For handling declarations that occur via meta-programming, we are going to explore both options through our addon system and through RBS files. RBS is significantly more expressive and thus we will favour support for that for manually written annotations. And with the addon system we hope to provide APIs for other gems to teach the indexer how to handle their meta-programming DSLs
erickguan commented 3 months ago

Thanks. Good to know the plans for Ruby LSP.