Proposal: @sig for ::

[palkan]

Hey @soutaro,

First, thanks for your work. I’ve been following this repo from the very first day and very excited of where it goes.

I have a suggestion regarding the primitive syntax—use # @sig instead of #:::

• The current syntax is shorter (guess, that’s the reason) but looks like something new and even foreign compared to @x annotations already used by existing tools (notably, YARD)

• It would make the syntax consistent (all annotations start with “@“)

• It’s more descriptive (readable/understandable), especially to those not yet familiar with RBS syntax.

The @sig notation is also inspired by one of the prominent Ruby projects—Zeitwerk (example). It’s used there for information purpose only but looks very coherent with the rest of the documentation.

We can probably reuse @rbs instead of introducing a new annotation, too:

# @rbs () -> String
def to_s
end

# @rbs (?Regexp?) -> Enumerator[String, void]
# @rbs (?Regexp?) { (String) -> void } -> void
def each_person(pattern = nil, &block)
end

Since a signature must start with a ( (right?), I think, we can distinguish it from other annotations.

P.S. Now, looking at the example, I think that @sig would look better: it’s clear to even non-Ruby engineers that it’s a method signature (reminds of Erlang’s -spec), while @rbs is too Ruby-specific.

[soutaro]

Thank you for your feedback!

The #:: syntax is introduced for people who loves more compact syntax, even though a little bit cryptic. I'm open to add something equivalent to it for method types. @rbs method: () -> String was in my mind, but @rbs () -> String looks good too.

Do you think having @sig replacing all of @rbs?

# @sig generic A < BasicObject
class Foo < Bar
  # @sig @name: String

  # @sig name: String
  # @sig yields (Foo) -> void
  def initialize(name) #:: void
  end

  # @sig (String) -> EmailResult?
  def send_email(content)
  end
end

Hmm, not too bad.

[palkan]

Do you think having @sig replacing all of @rbs?

Yeah. The example you provided above looks more readable to me (especially the #send_mail method). Though I understand that’s it’s subjective (so, with discussing with broader audience; maybe, at/after Kaigi?).

[jaredcwhite]

@soutaro @palkan Honestly that syntax with @sig looks quite nice to me. Feels immediately understandable.

[ParadoxV5]

[Moved from Discord]

I was against the #: (single colon) syntax, but now it looks good enough to me. Maybe it will be changed to #: from #::.

So what was your reason against #: originally @soutaro? Could it be a conflict with Steep? I rather look forward to Steep depending on rbs-inline so it doesn’t have to maintain its own set.

---

I’m split with changing to @sig, but a background on the sig/ folder for RBS would help me decide. Using the sig name (for either this annotation and that folder) is taking RBS beïng Ruby’s “official” (gradual) static type system for granted. The rbs name (for either) is much more explicit (esp. vs. Sorbet).

[soutaro]

No conclusion yet for @sig, while I'm okay for either of the two.

#: syntax conflicts with Steep annotation. attr_reader :name #: String in Steep is a type assertion on the result of the method call. So, my plan for this is:

1. attr_reader-ish are special for Steep that the #: is not type assertion
2. May add another type assertion syntax to Steep for the case we need it, # @as or something else. Like TS has <T> and as T.

[ParadoxV5]

1. attr_reader-ish are special for Steep that the #: is not type assertion

• Resolved by soutaro/steep#1176
• Relates to soutaro/steep#1179

[soutaro]

I decided to go with @rbs, not @sig.

@rbs is safer and clear enough for people working around this area. @sig would make sense too, but not now. We can add the syntax in future.