2019年4月2日火曜日

YARD 入門

概要
環境
インストール
サンプルコード　
説明
- @params
- @return
- @author
- @overload
- @!attribute
最後に
参考サイト

概要

前回 rdoc に入門しました
今回は YARD を使ってみました

環境

macOS 10.14.3
Ruby 2.5.1p57

インストール

bundle init
chmod 644 Gemfile
vim Gemfile

gem "yard"

bundle install --path vendor

サンプルコード　

# Credit card data
#
# @author hawksnowlog
class Card
  def initialize(number, cvv, name)
    @number = number
    @cvv = cvv
    @name = name
    @enable = true
  end

  # @!attribute [rw] cvv
  #   be careful cvv leaking
  attr_accessor :number, :cvv, :name, :enable
end

# Management my credit cards
#
# @author hawksnowlog
class Cards
  # @overload initialize
  #   set empty my card list
  def initialize
    @my_cards = []
  end

  # To register new credit card
  # 
  # @param number [String] credit card number
  # @param cvv [String] credit card security code
  # @param name [String] credit card holder
  def register(number = '0000-1111-2222-3333', cvv = '123', name = 'hawk')
    c = Card.new(number, cvv, name)
    @my_cards.push(c)
  end

  # Unregister a credit card
  # 
  # @param number [String] credit card number
  # @return [Boolean] true if a credit card is unregisterd
  def unregister(number)
    c = @my_cards.select { |c|
      c if c.number == number
    }
    if c.empty?
      return false
    else
      c.first.enable = false
      return true
    end
  end

  # Show all of cards
  def list
    @my_cards.each { |c|
      puts "number => #{c.number}"
      puts "cvv    => #{c.cvv}"
      puts "name   => #{c.name}"
      puts "enable => #{c.enable}"
    }
  end

  # Select a card randomly
  # 
  # @return [Card] a card obj
  def random
    @my_cards.sample
  end
end

cards = Cards.new
cards.register
puts cards.unregister('0000-1111-2222-3333')
puts cards.unregister('0000-1111-2222-4444')
cards.list

bundle exec yard doc app.rb
open doc/index.html

でドキュメントが生成、確認できます
以下でタグなど書き方について詳細に説明します

説明

YARD にはいろいろなタグがあります
これを使うことで簡単にパラメータや返り値などのドキュメンテーションが行えます
全部で 30 個ほどありますがさすがに全ては試していないので今回試した @params, @return, @author, @overload, @!attribute の 5 つについて説明します

@params

メソッドの引数の説明に使います

# @param number [String] credit card number

引数名、クラス、説明文の構成になっています
参照可能なクラスがある場合は自動的にリンクにしてくれます
またメソッド側でデフォルト値を指定している場合は自動で拾ってドキュメンテーションしてくれます

@return

返り値の説明に使います

# @return [Card] a card obj

クラス、説明文の構成になっています
改行して 2 行目に続けて説明文を書くこともできます
@param 同様、返り値がクラスのオブジェクトの場合参照可能であればリンクが自動的に作成されます

@author

作者の説明に使います
今回はクラスにだけ使っていますがメソッドにも使えます

# @author hawksnowlog

作者の名前を記載します
特にフォーマットは決まっておらず自由に書けます
よく Your Name <yourname@mail> みたいな感じでメールの from みたいに各パターンを見かけます

@overload

自動で生成されるドキュメントをオーバーロードして自分のドキュメントで上書きすることができます
YARD は initialize や attr_accessor メソッドに関しては自動で説明文を追加してくれます
ですがそれらが気に入らない場合 @overlaod を使うことで上書きすることができます

# @overload initialize
#   set empty my card list

関数名、説明文の構成になっています
オーバーロードする関数名を必ず指定しなければなりません
パラメータがある場合は initialize(a, b) のように書きます
あとは引数が可変長の場合に指定する引数のパターンごとに @overload でドキュメンテーションする手法もあるようです

@!attribute

attr_accessor などの attr_* 系のメソッドに使うためのタグです

# @!attribute [rw] cvv
#   be careful cvv leaking

権限、属性名、説明文の構成になっています
先程説明したように attr_accessor は自動でドキュメントしてくれます
なので各アクセサの説明を独自で入れたい場合に使います
[rw] の場合 attr_accessor の意味になります
r だけなら attr_reader、 w だけなら attr_writer になります

最後に

YARD に入門してみました
rdoc に比べてタグが豊富にあるのでタグを使っていれば勝手に整形されるので楽です
rdoc の場合、自分でマークアップする感じなのでそれに比べ自由度は低いですが決められたフォーマット通りに書くだけなので気にすることが少ないです

YARD のタブは deprecated になっているものもあるのでドキュメントを確認して使わないようにしましょう

参考サイト

https://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md

hawksnowlog