Update to my YARD-docs generator: two-way RBS sync, source-aware fixes, IDE plugins

[u/XPOM-XAPTC]

I posted about docscribe here in March https://www.reddit.com/r/ruby/s/SVoDOzVoOs. Since then it reached 1.6.2, and I run it daily on client Rails apps. This is what's new.

The pain that started it: comments lie.

# @param [String] count
# @return [String]
def notify(verbose:, count:)
  puts "verbose!" if verbose # Boolean
  count.times { send_ping } # Integer
  count # Integer
end

After docscribe -a. Tags fixed, prose placeholders added (customizable in config), body untouched.

# @param [Boolean] verbose Param documentation.
# @param [Integer] count Param documentation.
# @return [Integer]
def notify(verbose:, count:)
  puts "verbose!" if verbose
  count.times { send_ping }
  count
end

What docscribe -a does: fixes the tags, keeps your prose. -A rebuilds the block from scratch.

New since March:

• update_types: RBS -> YARD two-pass; docscribe rbs goes the other way, YARD -> RBS
• every change carries source: rbs/infer/syntax, so the editor offers "Update types" vs "Fix YARD" correctly
• daemon mode keeps the VS Code and RubyMine plugins instant: docscribe-vscode and docscribe-rubymine
• CI mode runs on exit codes, check_for_comments, json/sarif output

One Rails-specific thing I use a lot: types from schema.rb, not from code. t.boolean :is_admin becomes @!attribute [r] is_admin -> Boolean in the model. No hand-written docs for columns.

Next in 1.7.0: docscribe sorbet - same YARD -> sig flow as docscribe rbs, but generating .rbi/sig blocks for srb tc. Plus validate_types on by default (opt-out with --no-validate-types). Plus tighter metaprogramming support: better types for define_method and DSL-generated methods, less Object fallback.

Limits now: heuristics, not a prover, so metaprogramming lands in Object. Each release narrows that gap. I always git diff after -A.

Question: do you keep YARD and RBS in sync by hand, or did you give up on one of them?

Live demo: unurgunite.github.io/docscribe

Source: github.com/unurgunite/docscribe

Gem: rubygems.org/gems/docscribe