phpDocumentor形式のドキュメントブロックを生成するvimプラグイン

Web制作ツール

2007.10.17

こんにちは。JavaScriptってPythonに似ているってことがだんだんわかってきたtanakaです。

みなさん、PHPでソースコード内ドキュメント、書いてますか。僕は今まで割とさぼりぎみでした。ごめんなさい。しかし、これから紹介するvimプラグインでドキュメントブロックを無理なく書いていけるでしょう。

さて、phpソースコード内の

    /**
     * index 
     * 
     * @param string $hoge 
     * @param array $fuga 
     * @access public
     * @return void
     */
    function index($hoge='hoge', $fuga=array())
    {
    }

といった風に、メソッドやクラスの宣言の前に整形されたコメントが記述されているのを見たことがある方もいると思います。何のためにプログラムの実行に影響しないこんなものを書くのかというと、プログラマがプログラムを読むのを助けたり、関数の利用の仕方を伝達するために書くものです。

でも、こんなブロックをエディタで打ち込むのはめんどくさいですよね？僕もいままで、/**[enter][space]*...って感じで打ち込んでいました。そんなことをやっているうちに、だんだん書きたくなくなってきて、書くのをわすれることもあったと思います。そこで、今日紹介するのはこのドキュメントブロックを自動生成してくれるvimプラグインです。

すこし導入に手間がかかります。まず、PDV - phpDocumentor for Vimからphp-doc.vimをダウンロードして、vimのpluginフォルダに置きます。そのあと、php-doc.vimを修正します。

php-doc.vim 77 - 83 行目

" Default values
let g:pdv_cfg_Type = "mixed"
let g:pdv_cfg_Package = ""
let g:pdv_cfg_Version = "$id$"
let g:pdv_cfg_Author = "Tanaka <tanaka@example.com>"
let g:pdv_cfg_Copyright = "200X-201X C-brains Corporation."
let g:pdv_cfg_License = "Hoge Lisence"

こんな感じで自分の名前や所属組織などにあわせてカスタマイズしてください。さらに、キーバインドの設定もします。

~/.vimrc(~/_vimrc)

" source ~/.vim/php-doc.vim
inoremap <C-P> <ESC>:call PhpDocSingle()<CR>i
nnoremap <C-P> :call PhpDocSingle()<CR>
vnoremap <C-P> :call PhpDocRange()<CR>

C-Pの所は、自分の好みに合わせて、普段使っていないキーバインドを設定してください。これで設定は終わりです。実際に使ってみましょう。

普段の作業環境で首尾良くドキュメントブロックの書かれていないソースコードを見つけたら…(失礼)、クラスや関数の宣言行にカーソルを合わせて、Ctrl+Pを押してください。どのモードであるかは問いません。すると、先ほど紹介したようなドキュメントブロックが挿入されたと思います。あとは、実際と異なる部分を修正してください。

どんなことを書けばいいか知りたいときは、phpDocumentor Guide to Creating Fantastic Documentationを見るか、phpDocumentor - scriptlife.hacca.jpも参考になると思います。