Merge sigs in RBI files with existing documentation

[dduugg]

This PR updates the sig handler to check the YARD::Registry for existing documentation. If found, it will incorporate the sig information into the existing documentation. Otherwise, it will proceed as before, converting the sig into YARD documentation for normal processing.

wdyt @KaanOzkan @jscheid ❓

Resolves #141

[codecov]

Codecov Report

Base: 100.00% // Head: 100.00% // No change to project coverage 👍

Coverage data is based on head (2375f3f) compared to base (601ba16).
Patch coverage: 100.00% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #170   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           22        22           
  Lines          753       826   +73     
=========================================
+ Hits           753       826   +73     

Impacted Files	Coverage Δ
lib/yard-sorbet/handlers/sig_handler.rb	100.00% <100.00%> (ø)
lib/yard-sorbet/node_utils.rb	100.00% <100.00%> (ø)
spec/yard_sorbet/handlers/sig_handler_spec.rb	100.00% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[dduugg]

I had some time to add (limited) attr support, so marking this as ready for review. Note that it seems that the primary interest here is in tapioca output, and AFAICT tapioca doesn't output attr*s.

The limited support is that we will only attempt to merge documentation if an attr* has a single parameter. The reason is that we remove the docstring once we've merged it into an existing docstring in the registry. If we support multiple attr* parameters, we may see a mix of registered and unregistered attributes. That would add a lot of complexity to the AST rewrite, for what feels like a niche use of rbi style.

[KaanOzkan]

LGTM as far as documenting RBIs more accurately 🙂

[jscheid]

Hi guys, thanks for building this! Sorry I didn't get a chance to take a look at it before. I'm trying to implement it now but I'm running into SystemStackError: stack level too deep. This is with yard server.

I've already doubled the stack, then 10x, by setting RUBY_THREAD_VM_STACK_SIZE in the shell that invokes bundle exec yard server (thinking that maybe it's not infinite recursion, just hungry) but same result. I'm not yet sure how I can verify that the setting took hold, any ideas?

Here is the full backtrace with RUBY_THREAD_VM_STACK_SIZE=20971520: https://gist.github.com/jscheid/73177e982b2983e4aeb94e590043429e

[dduugg]

@jscheid to be clear, is bumping the yard-sorbet version the only change that you've made to produce the error? A few things to try:

1. There's a yard PR to fix a stack overflow issue, does that resolve your problem?
2. Can you bisect your codebase to find the offending file(s)? (Trim the contents consumed by yard until you have the smallest subset that will repro the problem.)
3. Try adding some print lines to display the node source, and see if there's something that might be triggering a stack loop.

Let me know if you uncover any hints this way.

[jscheid]

@jscheid to be clear, is bumping the yard-sorbet version the only change that you've made to produce the error?

There's no stack overflow if I don't specify the RBI files on the command line.

Let me know if you uncover any hints this way.

OK, I'll dig in. I just thought you had any ideas just from looking at the backtrace.

[Skipants]

@jscheid Definitely try yard-sorbet with the fix to the yard gem @dduugg linked above.

If yard-sorbet adds more objects to YARD::Registry, which it seems to do, then that PR could fix your issue. The problem solved by that PR is that YARD currently does a recursive call that can blow up the call stack at a pace exponential to the size of that YARD::Registry. That causes the stack overflow.