Providing additional description to params

[topherfangio]

Suppose I have a method like follows:

sig { params(value: String, algorithm: Symbol).returns(String) }
def redact(value, algorithm)
  ...
end

Is there a good way of providing an additional description for the params or the return type? Or do we just have to type that in the standard YARD docs?

Thanks!

[KaanOzkan]

There's no built in way of adding documentation inside a sig for Sorbet. And yard-sorbet focuses on making Sorbet expressions available in yard documentation. In your case best path forward would be to use YARD syntax as you mentioned.

I don't really see a benefit over YARD but wanted to mention that you can also split the sig into multiple lines and add comments for each parameter as well:

sig do
  params(
    value: String, # ...
    algorithm: Symbol, # ...
  ).returns(String) # ...
end
def foo; end

[topherfangio]

@KaanOzkan Ok, thanks for the info!

[dduugg]

I'd be open to supporting such comments – I don't love writing the param name three times in these cases (as a YARD annotation, sig, and method def). I would want the Shopify folks such as @KaanOzkan to be on board though.

Note that there is a fork with a change that incorporates inline comments into the generated documentation, but they never attempted to upstream the change.

[KaanOzkan]

Good point @dduugg on the verbosity. I personally haven't reached for this feature yet but supporting also makes sense to me since yard-sorbet already exposes comments on the line before a sig as YARD documentation. 👍

[dduugg]

Ah, right, I'd forgotten about that. I'm just as happy to support having one correct way to annotate params without using verbose YARD annotations. Thanks!