Help us understand the problem. What is going on with this article?

YARD,RDoc 比較

More than 5 years have passed since last update.

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はない
  • @~ というタグで、パラメータ/返り値/サンプルコード などを記述できる

タグ

http://rubydoc.info/docs/yard/file/docs/Tags.md#Tag_List

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

    • 例: @paramsの構文は "@params [型] 名前 説明"が正しいが、型と名前が逆に書かれている
  • よく使いそうなタグ

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

便利そうな機能

$ yard diff new old

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

比較

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
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした