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}
などとする。
ATOM Feed