Run YARD as RSpec

#ruby #rspec #yard

Let me introduce yardspec in this article.

yardspec is a Ruby gem that supports executing YARD documentation @examples as RSpec examples.

module Foo
  class Bar
    # @example returns "baz"
    #   expect(Foo::Bar.new.baz).to eq('baz')
    #
    # @example returns "bazbaz" for count 2
    #   expect(Foo::Bar.new.baz(count: 2)).to eq('bazbaz')
    #
    # @return [String]
    def baz(count: 1)
      'baz' * count
    end
  end
end

It interprets the documentation examples above as the following RSpec examples:

RSpec.describe 'Foo::Bar#baz' do
  it 'returns "baz"' do
    expect(Foo::Bar.new.baz).to eq('baz')
  end

  it 'returns "bazbaz" for count 2' do
    expect(Foo::Bar.new.baz(count: 2)).to eq('bazbaz')
  end
end

and running RSpec as follows will automatically test them.

$ bundle exec rspec

Foo::Bar#baz
  returns "baz"
  returns "bazbaz" for count 2

Finished in 0.00129 seconds (files took 0.087 seconds to load)
2 examples, 0 failures

As you may have noticed, this is the doctest concept from Rust, Python, Elixir, etc, dropped into RSpec and YARD for Ruby.

It is often helpful to include example code in your documentation and demonstrate the results of executing them. But it is important to ensure that the documentation stays up-to-date with the code.

That is the purpose for which yardspec was created. By writing example code that actually works, users can read it with confidence and try it out for themselves.

How to Diagram Your Cloud Architecture

Cloud architecture diagrams provide critical visibility into the resources in your environment and how they’re connected. In our latest eBook, AWS Solution Architects Jason Mimick and James Wenzel walk through best practices on how to build effective and professional diagrams.

Download the Free eBook