RubyのYardでドキュメントを生成する方法・使い方

RubyのYardでドキュメントを生成する方法を紹介します。そもそも、yardというのはrubyの各メソッドやクラスに対してコメントを書きそれをもとに、 API（技術的な）ドキュメントを生成するものです。

Yardを使うと、 https://www.rubydoc.info/gems/yard/file/README.md

のが簡単にできてしまいます。さて、yardの使い方ですがまずは、gemなりでインストールする必要があります。

gem install yard

次に、ドキュメントの生成方法は簡単で、下記のようにすることでドキュメントを生成できます。 [ファイルの名前]は使う際に自分のファイルの名前にしてください。

yard doc [ファイルの名前]

あと、デフォルトでファイル名を指定しない場合は、lib,app, ext下にあるrubyファイルを勝手に拾って、ドキュメントかしてくれます。

ドキュメントする際にコメントを予め書く必要があり、今回は最も使うものを2つ紹介したいと思います。

params, return
@example

引数と返り値の説明

たとえば、下記のようなメソッドがあれば以下のように書きます。 @paramで引数を説明し、@paramの次に来るのが実際に利用する引数名です。 []が引数でとり得るクラスを書きます。

class
 # 挨拶をするメソッド
 # @param greeting [String] 文字列を引数としてとります。
 # @return [Nil] 戻り値はnilを返します
  def say_hi(greeting)
   puts greeting
  end
end

コードの例

やはりドキュメントに欠かせないのが、使用例かと思います。使用例は@exampleを使って実現でき、下記のようになります。下記のようにして、@exampleの後にtabを使って、その下にコードを書いてあげます。出力は#>の形を利用してあげることでそれが出力や実行後の中身を示すということをわかるようになります。

class
 # 挨拶をするメソッド
 # @example say_hiを使用した例
 #    say_hi("こんにちは") #> こんにちは
 # @param greeting [String] 文字列を引数としてとります。
 # @return [Nil] 戻り値はnilを返します
  def say_hi(greeting)
   puts greeting
  end
end

参考: Yard GettingStarted.md