docstring を挿入するプラグインを作った

Vim

Vim を使って PHP スクリプトを作成しているときに phpdoc.vim というプラグインがもの凄く重宝してた。
何をするものかというと、例えば以下のようなコードがあったとする。

<?php
class Foo
{
    pubilic function __construct($arg1, $arg2)
    {
    }
}

class や function の行にカーソルがある場合に

:call PhpDocSingle()

と実行すると

<?php
class ClassName
{
    /**
     * __construct
     *
     * @param mixed $arg1
     * @param mixed $arg2
     * @access public
     * @return void
     */
    public function __construct($arg1, $arg2)
    {
    }                          
}

といった感じでヘッダーコメントが挿入される。
この機能が地味に便利で、Python なコードを書いている時も自動で docstring が挿入して欲しい。
少し探してみたが無かったので、自分で作ってみた(Vim Script を一から書いたのは初めて)。
https://github.com/heavenshell/vim-pydocstring

# -*- coding: utf-8 -*-
def foo(arg):
    pass

これで :Pydocstring を呼ぶと

def foo(arg):
    """foo

    :param arg:
    """
    pass

というのが挿入される。
引数が無い場合は

def foo():
    """foo"""
    pass

ワンラインの docstring となる。


\ によって改行が入ってる場合は

def foo(arg1, \
            arg2):
    """foo

    :param arg1:
    :param arg2:
    """
    pass

となる。


差し込む docstring はテンプレートファイルになっているので、デフォルトのが気に入らなければ書き換える事ができる。
またテンプレートファイルの場所は

let g:pydocstring_templates_dir = '/path/to/temlate/'

といったようにテンプレートディレクトリを指定できる。
デフォルトでは ~/.vim/template/pydocstring/ としている。
# pathogen とかを使っていると、~/.vim/bundle/vim-pydocstring/template/pydocstring/


テンプレート内で使用できる変数は {{_header_}} と {{_args_}} の二つだけ。
{{_header_}} はクラス名|関数名|メソッド名で、{{_args_}} は引数が全て挿入される。


Python のメソッドやクラスメソッドは引数の一つめを self や cls といったキーワードを設定する。
そのため docstring には表示しないようにデフォルトではなっている。

let g:pydocstring_ignore_args_pattern = 'self\|cls'

cls は docstring として表示したい場合は self といったように Vim 正規表現を設定する。


キーマップはデフォルトで

nmap <silent> <C-l> <Plug>(pydocstring)

と設定している。
class や def の上で を押すと docstring が自動で挿入される。
class や def が無い所で を実行するとコメント行が挿入するようにしている。

let g:pydocstring_enable_comment = 0

とする事でコメントを挿入しないようになる。


Vim Script を初めて書いていて、こういう書き方でいいのかなと悩みながら書いたので正直全く自信がない。
書いている途中で分からない事を呟いてたら、[twitter:@kaoriya] さんや [twitter:@mattn_jp] さんにアドバイス頂きました。
ありがとうございます！