iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
There is no automatic two-way sync between YARD and RBS. Keep RBS as the type contract and YARD as the place for API explanations, then update both in the same change whenever public behavior changes. Use generated signatures as drafts, not authoritative declarations, and validate the signatures in your regular development workflow.
Why YARD and RBS need separate jobs
YARD documents Ruby APIs through comments and structured tags, including parameter and return information. Those type fields are largely convention-based and free-form; they are not a formal type contract.
RBS is a language for declaring the structure and types of Ruby programs in signature files. Treat the two formats as complementary: use RBS for types that tools can check, and use YARD for explanations, examples, and usage guidance. Keeping type descriptions in both places without assigning them distinct roles invites drift.
Free tools Windows power users keep installed
One-click scans. No signup required.
Set a source of truth before changing code
If your project uses RBS-based checking, make the RBS signature the source of truth for type contracts. YARD remains the source for explanatory documentation. This is not a claim that one format replaces the other: they answer different questions.
#1 Best Overall
- RBS: What structure, arguments, and return types does the program declare?
- YARD: What does the API do, how should callers use it, and what behavior needs explanation?
Before adopting commands or CI configuration, check the Ruby, YARD, RBS, and type-checker versions in your repository. The appropriate setup depends on those versions and on whether you intend to hand-author signatures or generate an initial draft.
Update implementation, YARD, and RBS in one change
For a new or changed public method, include the implementation, its YARD documentation, and its RBS declaration in the same pull request. Review them against actual behavior rather than allowing either description to become a copy of the other.
- Do the declared parameter names match the method?
- Are required and optional arguments represented correctly?
- Do overloads reflect the supported call patterns?
- Does the return type cover the values the implementation can actually return?
- Are relevant edge cases and behavior explained in YARD?
For a private implementation change that leaves the public API and behavior unchanged, the documentation may not need an edit. The useful trigger is a change to the public contract or to behavior a caller relies on.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsUse generated RBS as a first draft, not a verdict
The RBS project provides rbs prototype rb to generate initial declarations from Ruby source. Use it to reduce blank-page work in an existing codebase, then review and edit the result. The RBS README cautions: “This is only a starting point, and you should edit the output to match your signature more accurately.” RBS README: Prototype
Pay particular attention to declarations marked untyped and to inferred shapes that may not capture the intended contract. Generated output reflects what the tool can derive from source; it does not decide whether that inferred type is accurate, complete, or appropriate for callers.
Make signature checks part of the workflow
Run RBS signature validation in CI so changes that make declarations invalid are caught before merge. RBS also offers runtime signature testing: it can instrument selected methods and check observed argument and return values against declarations. Consider that for important APIs where checking real calls is valuable. RBS README: Runtime Type Checking
Rank #4
Choose commands and configuration that match the versions and tools your project actually uses; no single CI setup can be prescribed without that context. Validation checks signatures, while runtime tests check selected observed behavior. Neither removes the need to review whether YARD’s explanations and RBS’s contract still describe the intended public API.
Handle missing dependency signatures separately
If a dependency does not ship RBS definitions, an RBS collection may provide them; alternatively, maintain a project-local signature. The collection addresses missing type definitions for dependencies. It does not synchronize your own YARD comments with your own RBS signatures. RBS README: RBS Collection
Best Value
What “in sync” should mean in practice
A community post frames the frustration as: “do you keep YARD and RBS in sync by hand, or did you give up on one of them?” That is an informal question, not evidence of how Ruby developers generally work. A maintainable answer is to avoid duplicate type authority: RBS defines the type contract, YARD explains the API, and both are reviewed together when public behavior changes. The official YARD and RBS materials describe their respective formats and behavior; they do not establish built-in automatic two-way synchronization.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
