Ecosystem question: YARD?

[jaredcwhite]

I've spent a bit of time with this and I'm quite pleased with the concept and the workflow even in this early stage. Kudos!

I think there's a fantastic opportunity here to zoom out to the ecosystem level and really fine-tune the DX around authoring code, documentation, type hints, and checking all as a single unit of effort—as is possible in many other language ecosystems.

To that end, what might the relationship be between these inline RBS comments and YARDoc? Consider the following:

# Convert a Markdown string into HTML output.
#
# @param input [String] the Markdown to convert
# @return [String]
def markdownify(input)
  # ...
end

With RBS inline, I could instead write this:

# Convert a Markdown string into HTML output.
#
# @rbs input: String - the Markdown to convert
# @rbs returns String
def markdownify(input)
  # ...
end

But now I'm not going to get documentation for my code. Would I have to duplicate?

# Convert a Markdown string into HTML output.
#
# @rbs input: String
# @param input [String] the Markdown to convert
# @rbs returns String
# @return [String]
def markdownify(input)
  # ...
end

Hmm. 😐

A few possible directions to go:

• Add @rbs tag support to YARD. I honestly have no idea how easy that might be though.
• Support some common YARD tags in addition to @rbs. This starts wading into https://github.com/AaronC81/sord territory though, not sure if that would ever be in scope.
• Add or document modular plugin feature so a third-party could offer support for YARD tags.

For additional context, I've been using YARD + Solargraph + VSCode for my Ruby dev environment for several years now, and the experience is pretty good overall (even though I'm not using it for type checking, just autocomplete/tips/jump/etc.). I'd love to see a day I can use YARD + Steep with inline RBS and really get a best-of-all-worlds experience. 🤩

[soutaro]

Hi! Thank you for your feedback. The concern totally makes sense.

We designed the syntax based on our observation that people are not using the yardoc command, but just using the syntax to read the docs on the source code. The assumption may be bad?

We decided not to use the YARD comments -- @param and @returns -- directly because:

1. They are okay, but we need more annotations. We don't want to have both @param and @rbs annotations to avoid confusion.
2. We plan to merge the syntax to rbs-gem, which is bundled in Ruby distribution, where we don't have yard gem.
3. It also requires some rewrites because the type syntax is different.

To avoid the duplication, we have some plans:

1. Supporting some YARD syntaxes that can easily be used for type definition, like @param and @return
2. Providing a YARD plugin to support converting @rbs methods for documentation generation

For the plugin development, supporting @!rbs syntax too in addition to @rbs would make sense to help development of the YARD directives which generates YARD tags.

[jaredcwhite]

@soutaro I appreciate your detailed reply! Sounds like you've given this some thought and that all makes sense to me. ☺️

[ParadoxV5]

We designed the syntax based on our observation that people are not using the yardoc command, but just using the syntax to read the docs on the source code. The assumption may be bad?

A frog in a well.
Even if people seldom run yardoc/yard doc manually or in their own CIs, where does https://rubydoc.info come from?

1. Supporting some YARD syntaxes that can easily be used for type definition, like @param and @return

-1.
Type annotations for @param, @return and etc. follow YARD’s conventions that came before and is different from RBS, and this difference require (if not depend on) (parts of) the aforementioned Sord to bridge for one of the sides, which bloats RBS(::Inline)’s scope and/or code, especially that:

2. We plan to merge the syntax to rbs-gem, which is bundled in Ruby distribution, where we don't have yard gem.

Looking forward to becoming mainstream! 🚀

2. Providing a YARD plugin to support converting @rbs methods for documentation generation

🆙

YARD doesn’t mandate the aforementioned conventions de facto, and I’ve abused this to include RBSs in YARD.
It mostly works, but there’re visible cosmetic incompatibilities as the renderer parses the RBS using YARD conventions.

---

We

Who’s ‘we’? GitHub’s records show that only you’ve been coding? Did @pocke review (offline?)? I know, as community-driven clubs, open-source projects love the Royal We 😄.

[soutaro]

The observation people are not using the yardoc command is based on my experience working in a company, or some interviews to colleagues by @mame, @pocke, and myself. Your comment about rubydoc.info makes sense though.

So the revised plan for this would be: providing a YARD plugin to support @rbs annotations (or send the patch to YARD).

[svoop]

@soutaro

So the revised plan for this would be: providing a YARD plugin to support @rbs annotations (or send the patch to YARD).

Sounds solid and shouldn't bee too hard to transition to @rbs notation – maybe a simple tool could even translate the 98% easy cases.

How do you plan to accommodate the prose, though? I quite like the suggestion of @jaredcwhite:

# @rbs input: String - the Markdown to convert

In real life, the prose may be lengthy, so multiline would be nice:

# @rbs input: String - the Markdown to convert limited as per the config of the
#   sanitation service yaddah yaddah blah blah

[soutaro]

@svoop I have a few notes.

Put double hyphens before the comment, --.

# @rbs input: String -- the Markdown to convert

And you can continue a type declaration with indentations for multiline comments/types.

# @rbs input: String --
#   the Markdown to convert limited as per the config of the
#   sanitation service yaddah yaddah blah blah
# @rbs another: Integer --
#   Some number

In fact, we converted existing YARD tags to @rbs comments in our Rails app in Timee using this script. Only a few YARD type constructs are supported, but it covers most of our YARD tags.

(We have a blog post about the migration but it's in Japanese...)