Запуск YARD как RSpec

Позвольте представить вам yardspec в этой статье.

yardspec — это Ruby gem, который поддерживает выполнение документации YARD @example в качестве примеров RSpec.

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

Он интерпретирует приведенные выше примеры документации как следующие примеры RSpec:

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

и запуск RSpec следующим образом автоматически протестирует их.

$ 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

Как вы могли заметить, это концепция doctest из Rust, Python, Elixir и т.д., перенесенная в RSpec и YARD для Ruby.

Часто бывает полезно включить в документацию примеры кода и продемонстрировать результаты их выполнения. Но важно, чтобы документация оставалась актуальной по отношению к коду.

Именно для этой цели и был создан yardspec. Написав пример кода, который действительно работает, пользователи могут с уверенностью прочитать его и опробовать самостоятельно.

Дальнейшее чтение

• https://github.com/r7kamura/yardspec
  • исходный код yardspec
• https://www.rubydoc.info/gems/yard/file/docs/Tags.md#example
  • Тег YARD @example
• https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html
  • Rust doctest