Rdoc、素晴らしい！無知は怖い...。 - ザリガニが見ていた...。

昨日まで、Login Engineプラグインを利用するために、英語は苦手だが、READMEを必死に読んだ。READMEはこんな風に書かれている。

= Before we start

This is a Rails Engine version of the Salted Login Generator, a most excellent login system which is sufficient for most simple cases. For the most part, this code has not been altered from its generator form, with the following notable exceptions

* Localization has been removed.
* The 'welcome' page has been changed to the 'home' page
* A few new functions have been thrown in
* It's... uh.... a Rails Engine now ;-)

However, what I'm trying to say is that 99.9999% of the credit for this should go to Joe Hosteny, Tobias Luetke (xal) and the folks that worked on the original Salted Login generator code. I've just wrapped it into something runnable with the Rails Engine system.

Please also bear in mind that this is a work in progress, and things like testing are wildly up in the air... but they will fall into place very soon. And now, on with the show.


= Installation

Installing the Login Engine is fairly simple.

Your options are:
  1.  Install as a rails plugin:
      $ script/plugin install login_engine
  2.  Use svn:externals
      $ svn propedit svn:externals vendor/plugins
...（以下省略）...

なんだか、読み難いですね。

そして本日、User Engineプラグインの存在を知り、使ってみようと思って、やっぱりまた苦手な英語のREADMEを開いてみる。

= UserEngine: Login + Roles

The UserEngine extends the LoginEngine with a very, *very* simple implementation of RBAC - role based access control. As well as the 'User' object, the UserEngine provides Permission objects, and Role objects. Each User can have many Roles, and each Role is associated with many Permissions. A Permission is simple a controller/action pair. A Role which is associated with some permission has access to that specific controller/action, i.e. any Role associated with the Permission object "user/home" will be allowed to call that action.

=== Not the One True RBAC system

I'll make this point at the beginning, so there can be no doubt - this is *not* a full permission system. The UserEngine only controls which users have the right to hit which controller/action pairs. It will not control access to data at all, so for instance you cannot use it to give users the ability to edit only a subset of your data object (unless that subset is controlled via different controller actions).

= Installing

1. Create your Rails application, set up your databases, grab the Engines plugin and the LoginEngine, and install them.

2. Install the UserEngine into your vendor/plugins directory

3. Modify your Engines.start call in config/environment.rb - if you have specifically specified which Engines to start, ensure that you add :user (or :user_engine). The important point here is to note that the UserEngine must be started *after* the LoginEngine, since it will override a small amount of the behaviour in the latter. The end of your environment.rb file should look something like this:
...（以下省略）...

やっぱりまた、読み難い書式か、という感じ...。
こんなこと書くと、知っている人には笑われてしまうが、実はLogin EngineのREADMEを読む時は、苦手な英語を少しでも読み易くしようと、テキストエディット(MacOSX付属のエディタ)にコピーして、自分が読み易いように手作業で書式を整えていたのだ...。
プログラム書く人として、こんな単調な手作業は最もやってはいけないこと。もっと頭を使うべきだった。
だって、そんな手作業は必要なかったのだから...。

Rdoc発見の経過...

User EngineのREADMEを見て、再び、読み難い書式にガックリしたが、この書式はLogin Engineと同じじゃないか！ということに気付く。
よくよく見ると、自分の書いている「はてなブログ」の書式と、とっても似ているじゃないか...。
もしかしたら、この書式を変換してくれるツールがどこかにあるかもしれない...。
Googleで検索したら、Rdoc覚え書きがヒットした！
読んでるだけじゃよく分からないので、とにかくやってみる。
ターミナルを起動して、User EngineのREADMEのディレクトリに移動。以下のコマンドを実行した。

MacBook:~/railsapp/softwarebook2/vendor/plugins/user_engine zari$ rdoc README

すると、こんな表示が...。

                             README: 
Generating HTML...

Files:   1
Classes: 0
Modules: 0
Methods: 0
Elapsed: 0.476s

「Generating HTML...」なんて気になる表示が出たので、どこかにHTMLに変換されたファイルがあるはず、と思って探して見ると...
vendor/plugins/user_engine/doc/以下にHTMLファイル群が出来ている！webブラウザでindex.htmlを開いてみると...

なんと！読み易いページに変換されているではないか...。
そして、このページの書式にはどこか見覚えがある...。そうなのです、RailsのAPIドキュメントのページと同じだ！
さらに調べて、ターミナルで一つ上の階層に移動して、rdoc user_engineを実行すると、あっという間にuser_enginのAPIドキュメントの出来上がり！

こんな素晴らしい機能は、きっとRadRailsからも利用できるはずだと思って見てみると、「Rake タスク」タブのプルダウンメニューにdoc:pluginsを発見。実行してみる。
あっさり、Engines、Login Engine、User Engine、Specialプラグインすべてのマニュアルが出来てしまった！生成されるマニュアルの場所はsoftwarebook2/doc/pluginsフォルダの中。READMEとAPIがセットになった素晴らしいマニュアルだ。
ソースコードと、Rdocの内容を対比して見る。

class UserController < ApplicationController
  model   :user

  # Override this function in your own application to define a custom home action.......Rdocでの説明書きになる。
  def home
    if user?
      @fullname = "#{current_user.firstname} #{current_user.lastname}"
    else
      @fullname = "Not logged in..."
    end # this is a bit of a hack since the home action is used to verify user
        # keys, where noone is logged in. We should probably create a unique
        # 'validate_key' action instead.......Rdocの説明書きでは非表示。ソースを見ると表示される。
  end

  # The action used to log a user in. If the user was redirected to the login page
  # by the login_required method, they should be sent back to the page they were
  # trying to access. If not, they will be sent to "/user/home".......Rdocでの説明書きになる。
  def login
    return if generate_blank
    @user = User.new(params[:user])

Rdocのスクリーンショットが、ちょっと小さくて読み難いが...

メソッド定義の直前のコメントが、Rdocのメソッドを説明する内容になるようだ。
メソッド定義のブロック内に書かれたコメントはRdocの説明としては表示されない。ソースを見ると表示される。
RailsのAPIドキュメントのように[Source]をクリックすると、その部分のソースコードまで表示される。

教訓!!

Rubyを知らないままRailsを始めると、「Rdocを知らない」なんていう、こんなトンチンカンなことやってしまうんだなと。
最後にdocフォルダのREADMEを見てみると、ちゃんとヒントになることは書いてあった...。やっぱり英語と友達にならないとダメですね。

Use this README file to introduce your application and point to useful places in the API for learning more.
Run "rake appdoc" to generate API documentation for your models and controllers.

ちゃんと理解しようと、前向きに読まないと...。