Merge tapioca dsl output

[jscheid]

Great little plugin, thank you.

I wonder how feasible it would be to merge the RBIs generated by tapioca dsl into the output? It would be great to have dynamic ActiveRecord methods etc. in the docs.

[KaanOzkan]

I'm not 100% sure if it makes sense to have documentation for the generated methods because in some cases there will be way too many of them.

Regardless I don't think it's ayard-sorbet problem. Yard itself would need to parse and process .rbi files. I don't think there's anything yard-sorbet needs to do since nodes in the RBIs are just regular constants and method definitions.

[dduugg]

Hi @jscheid, thanks for the suggestion. This is something I've thought about, and I think could potentially add a lot of value (to avoid needing to switch between source code documentation and the type signature in a separate file).

@KaanOzkan is somewhat correct – yard-sorbet can already parse RBI files, but they will need to be explicitly included (e.g. as rbi/**/*.rbi in .yardopts). Doing so will clobber any existing documentation, however, as well as break the links to the source files in the YARD output.

A better approach would be to make a change in SigHandler to look for an existing docstring before falling back on the attached method's docstring (e.g. YARD::Registry.at(Foo::Bar#baz)&.docstring || statement.docstring) to attach the sig-based documentation. That should be enough to get you started, but I may have some bandwidth to work on this in the coming days/weeks.

[KaanOzkan]

@dduugg Oh yes good point that this can be done in yard-sorbet only. However, I'm not sure if the first part of the fallback (existing docstring) will ever happen since the DSL RBIs are dynamic method definitions that are only statically available in the RBI. Am I misinterpreting the example?

I do think clobbering can hurt the regular documentation as well. A good alternative we found was the Sorbet LSP which displays the DSL RBI upon hovering the call.

[dduugg]

@KaanOzkan there can be static method definitions that exist in both the .rb and .rbi files. For instance, when static type checking is desired but not the runtime component (and T::Sig::WithoutRuntime.sig is considered too verbose or is otherwise undesirable). I've considered taking yard-sorbet in this direction, FWIW.

I fully expect LSP to be a superior option wherever it's available 😸