YARD,RDoc 比較

• YARD - A Ruby Documentation Tool
  • http://yardoc.org/
• Rails/Rubyドキュメントをキレイに生成するYARD、早見表付き！ - 酒と泪とRubyとRailsと
  • http://morizyun.github.io/blog/yard-rails-ruby-gem-document-html/
• RDoc- Document Generator for Ruby Source
  • http://rdoc.sourceforge.net/
• library rdoc
  • http://doc.ruby-lang.org/ja/1.9.2/library/rdoc.html
• RDocの基本的な書き方メモ - maeshimaの日記
  • http://maeshima.hateblo.jp/entry/20100725/1280055512

---

RDocおさらい

• Rubyのソースコードから(HTML)ドキュメント生成を行うツール
  • ソースコードを解析し、クラス、モジュール、メソッドの定義を抜き出す
  • それとその直前に書かれたコメントを併合しドキュメントを生成する
• 現在はRubyの標準ライブラリ

コマンド

$ rdoc [options] [names...]

• カレントディレクトリいかにある全てのRuby,Cのソースからドキュメント生成

$ rdoc

• わからない場合はとりあえずhelp

$ rdoc --help

書き方

• コメント部は'#'では始まるもの、=begin/=end両方使える
  • =begin/=endの場合は、 rdocタグをつける必要あり

=begin rdoc
hogehoge
=end

見出し

#=
#==
#===

コメント

#--
# RDoc的なコメント
#++

リスト

• - / * で番号なしリスト
• 1. で番号付リスト
• a. でアルファベットリスト
• [ラベル]テキスト / ラベル::テキスト でラベル付きリスト

その他

• *テキスト* 太字(日本語、スペースは不可)
• _テキスト_ 斜体(〃)
• +テキスト+ 等角フォント(〃)
• <b>テキスト</b>(日本語など可)
• <em>テキスト</em>(〃)
• <tt>テキスト</tt>(〃)

YARD

YARD is a documentation generation tool for the Ruby programming language. It enables the user to generate consistent, usable documentation that can be? exported to a number of formats very easily, and also supports extending for custom Ruby constructs such as custom class level definitions. Above is a highlight of the some of YARD's notable features.

YARDは、Rubyプログラミング言語のドキュメント生成ツールです。これは、ユーザーがすることができ、一貫性のある使用可能なドキュメントを生成することができます？非常に簡単にフォーマットの数に輸出され、また、カスタムRubyはこのようなカスタム·クラス·レベルの定義として構築するための拡張をサポートしています。上記のYARDの注目すべき機能のいくつかのハイライトです。

利用方法

• gemからインストール

$ gem install yard

コマンド

• カレントディレクトリにある*.rbファイルについてドキュメント作成

$ yardoc *.rb

• 分からない場合はやはりヘルプ

$ yard --help
$ yardoc --help

書き方

• 特別なmarkupはない
• @～ というタグで、パラメータ/返り値/サンプルコード などを記述できる

タグ

• ただし書かれている内容にはしばしば誤りがあるので注意

  • 例： @paramsの構文は "@params [型] 名前 説明"が正しいが、型と名前が逆に書かれている

• よく使いそうなタグ

  • @param [引数のクラス] 引数名 引数の説明
  • @return [戻り値のクラス] 戻り値の説明
  • @option ハッシュ引数の名前 [値のクラス] キー名 説明
  • @example タイトル(任意) \n コードブロック

便利そうな機能

$ yard diff new old

• オブジェクトの追加/削除を知ることができる

比較

• http://rubydoc.info/docs/yard/file/docs/GettingStarted.md#Documenting_Code_with_YARD

RDoc

rdoc_sample.rb

class MyClass
  # Converts the object into textual markup given a specific `format`
  # (defaults to `:html`)
  #
  # == Parameters:
  # format::
  #   A Symbol declaring the format to convert the object to. This
  #   can be `:text` or `:html`.
  #
  # == Returns:
  # A string representing the object in a specified
  # format.
  #
  def to_format(format = :html)
    # format the object
  end
end

YARD

yard_sample.rb

class MyClass
  # Converts the object into textual markup given a specific format.
  #
  # @param [Symbol] format the format type, `:text` or `:html`
  # @return [String] the object converted into the expected format.
  def to_format(format = :html)
     # format the object
  end
end