YARD を使ってドキュメントを書く

YARD を使うと Ruby のソースコードに書いたコメントから きれいなドキュメントを生成できる。

使用できるタグの一覧は http://rubydoc.info/docs/yard/file/docs/Tags.md#List_of\_Available\_Tags にある。

ドキュメント生成にキャッシュを使う

キャッシュを使う。標準だと使用しないことになっている。

yardoc -c

yard のコマンドライン引数を保存する

.document に書く。 たとえば

lib/**/*.rb
bin/*
-
LICENSE.txt
docs/**/*.md

のようにする。

YARD のドキュメントをブラウザで見る

yard server --reload

でサーバを起動して http://localhost:8808 にアクセスする。

例を記述する

@example タグを使って、下に続く例は字下げする。

# @example A server over ssh
#  server(:server_ssh, "example.co.jp") do |server, ssh|
#    server.load "server_definition.rb"
#    server.acl "/path/to/acl"
#    ...
#  end

返り値を記述する

@return を使う。

# @return [Array] an array of pair [name symbol, definition hash]
# Keys of the hash are :type, :template, :ssh, :setting, and :args.
attr_reader :__server__, :__node__

オプション引数を記述する

@param でパラメータについて書いた後に、@option でキーと値について書く。

# We can set default server, default port, ... .
# @param [Hash] val the pair of key and value
# @option val [Fixnum] :port Port number of a server
# @option val [Symbol] :server Server executed by default
def default(val = {})

リンクを張る

オブジェクトにリンクを張るには { と } で囲んで

{SomeClass#some_method}

とする。URL やファイルにリンクを張るには

{http://example.com}
{file:/tmp/file.txt}

などとする。

Tags of current page

, ,