Open jaredcwhite opened 5 months ago
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:
@param
and @rbs
annotations to avoid confusion.yard
gem.To avoid the duplication, we have some plans:
@param
and @return
@rbs
methods for documentation generationFor 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.
@soutaro I appreciate your detailed reply! Sounds like you've given this some thought and that all makes sense to me. ☺️
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?
- 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:
- 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! 🚀
- Providing a YARD plugin to support converting
@rbs
methods for documentation generation
:up:
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 😄.
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).
@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
@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...)
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:
With RBS inline, I could instead write this:
But now I'm not going to get documentation for my code. Would I have to duplicate?
Hmm. 😐
A few possible directions to go:
@rbs
tag support to YARD. I honestly have no idea how easy that might be though.@rbs
. This starts wading into https://github.com/AaronC81/sord territory though, not sure if that would ever be in scope.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. 🤩