Support sorbet's `sig`

[christi-stripe]

See https://sorbet.org/docs/sigs for information on method signatures.

Given this example:

    # This is the mymethod1 comment
    sig do
      params(
        # This is an integer
        anint: Integer,
        # This is a string
        astring: String
      ).void
    end
    def self.mymethod1(anint, astring)
      # ...
    end

    # This is the mymethod2 comment
    def self.mymethod2(anint, astring)
      # ...
    end

    # This is the mymethod3 comment
    #
    # :args: anint, astring
    #
    def self.mymethod3(anint, astring)
      # ...
    end

the following markdown is generated:

 ### mymethod1(anint, astring) [](#method-c-mymethod1)
 ### mymethod2(anint, astring) [](#method-c-mymethod2)
 This is the mymethod2 comment

 ### mymethod3(anint, astring) [](#method-c-mymethod3)
 This is the mymethod3 comment

mymethod1 uses Sorbet's sig and you can see it has no generated documentation at all.

mymethod2 and mymethod3 do not use sig and the method comment is included in the generated markdown.

I attempted to use :args: with mymethod3 and it did not change anything, so I filed #37 separately.

~~mymethod4~~ moved to #39

[skatkov]

Thanks for giving this a try.

I assumed that this didn't work, but always wanted to take a better look at Sorbet.

It would be so great to have sorbet support added to this gem as well. Do you want to give it a shoot?

There is also official .rbs, as I understand, rbs types are always defined in a separate file. Thought, I haven't seen much rbs usage in a wild, but sorbet is definitely being used!

[skatkov]

mymethod4 uses the Rdoc syntax for @param as described here which includes the text in the markdown but does not format it properly.

This might deserve a separate issue. Great find!

[christi-stripe]

Interesting, I hadn't seen RBS before, reminds me of C header files.

I may look into Sorbet support but not sure if I'll have time, I was just trying this plugin while looking for a way to create documentation with custom Markdoc tags so I wouldn't be able to use this plugin out of box. If I'm able to spend time to make the custom Markdoc thing, I'll have to then port the Sorbet part back to this library.

Will file the @param issue separately.