最近のyard パーフェクトRuby Advent Calendar 2日目

Ruby

このエントリは パーフェクトRuby Advent Calendar の2日目のエントリです。

1日目のエントリはパーフェクトRuby Advent Calendar 2013(1日目) - すがブロです。

yard diff

いきなりですが、パーフェクトRubyで知った最高に便利なコマンドは yard diff です。

開発中でも、運用中でも利用するライブラリのバージョンアップは必ず発生します。依存関係がたくさんあるライブラリを使っていていると次のようなことが起こりがちです。

  • ○○を更新したら、○○の使っている△△が更新されて今まで動いていたものが動かなくなった
  • ○○の使っている□□を更新したいけど、よくわかんないし、仕事増えそうだからやめよう

こんなときに yard diffを利用すると便利。変更内容を俯瞰できるので、ソースを追ってやるという気持ちになれます。yardのことを全然知らなかったので、一年前にこのコマンドを知っていれば、、、と悔やまれます。

最近のyard

せっかくyardに興味を持ったので、最近のyardの変更を調べてみました。パーフェクトRubyではyard-0.8.2.1を使っていて、現在はyard-0.8.7.3がリリースされています。この間に次のような機能追加がありました。

asciidoc の追加

マークアップの記法にasciidocが利用できるようになりました。利用するためには事前にgem install asciidoctorしておく必要があります。マニアックですね。

yard markupsコマンドの追加

yard docで利用できるドキュメントの形式が一覧できるようになりました。

% yard markups
Available markup types for `doc' command:

[asciidoc]
  Providers: asciidoctor
  Extensions: .asciidoc .ad .adoc .asc

[html]
  Extensions: .htm .html .shtml

[markdown]
  Providers: redcarpet rdiscount kramdown bluecloth maruku rpeg-markdown rdoc
  Extensions: .markdown .md .mdown .mkd

[none]

[pre]

[rdoc]
  Extensions: .rdoc

[ruby]
  Extensions: .rb .ru

[text]
  Extensions: .txt

[textile]
  Providers: redcloth
  Extensions: .textile .txtile

[textile_strict]
  Providers: redcloth

yard display コマンドの追加

1クラスだけドキュメントを表示します。利用するには事前にyard doc -nで.yardocを作る必要があります。

% git clone https://github.com/rack/rack
% cd rack
% yard doc -n
Files:          64
Modules:        14 (    8 undocumented)
Classes:        82 (   34 undocumented)
Constants:      83 (   64 undocumented)
Methods:       464 (  249 undocumented)
 44.79% documented
% yard display Rack::Auth::Basic
----------------- Class: Rack::Auth::Basic < Rack::Auth::AbstractHandler

    Rack::Auth::Basic implements HTTP Basic Authentication, as per RFC
    2617.

    Initialize with the Rack application that you want protecting, and a
    block that checks if a username and password pair are valid.

    See also: <tt>example/protectedlobster.rb</tt>



------------------------------------------------------------------------

--layout onefileでHTMLを出力させると良い感じです

% yard display --layout onefile -f html Rack::Auth::Basic > rack-auth-basic.html

まとめ

yardなどのRubyで開発しているとまずインストールされているコマンド郡を、パーフェクトRubyはしっかり網羅してあります。調べるのをさぼっていた機能を勉強するのにとっても便利です。

次のアドベンターはid:t2osさんです！