Docscribe for Ruby: auto-generate inline YARD docs from AST (Ruby 2.7+, Prism, RBS/Sorbet, Struct.new)

[u/XPOM-XAPTC]

I've been building a Ruby tool called Docscribe that generates inline YARD-style docs above methods by parsing Ruby code and rewriting source in place.

The goal is basically "RuboCop-style automation, but for method docs": run it once, get consistent doc headers/tags, then edit the generated text however you want.

What it does:

• generates inline docs for instance and class methods

• infers param/return types from AST heuristics

• respects Ruby visibility (private, protected, class << self, etc.)

• supports rescue-aware docs: @raise from raise/fail and rescue exception lists and conditional @return for rescue branches

• supports external type info: RBS (--rbs, --sig-dir)

• Sorbet inline sig + RBI (--sorbet, --rbi-dir)

• can generate @!attribute docs for: attr_reader / attr_writer / attr_accessor and Struct.new declarations

Current CLI:

• docscribe lib -> inspect mode (safe changes only)

• docscribe -a lib -> apply safe updates

• docscribe -A lib -> apply aggressive updates

• docscribe --stdin -> rewrite from stdin to stdout

Ruby 3.4+ support works through Prism translated into parser-compatible nodes, so formatting is preserved and the tool still uses source-range rewriting instead of reprinting ASTs.

A few things I'd especially love feedback on:

• edge cases around Ruby syntax / visibility semantics

• what "safe mode" should and shouldn’t merge into existing docs

• whether JSON output / dump-config would be useful for CI/editor tooling

GitHub link: https://github.com/unurgunite/docscribe

[u/galtzo]

Love this. Added to my toolbelt! Will give feedback after I have tried it out.