Emacs Lisp 開発者にドキュメントの書き方を丁寧に教えてくれる checkdoc-minor-mode を有効にした


Emacsでの説明文字列

Emacsでの関数や変数には説明文字列をつけることができます。Emacs Lispで何がしかの拡張を書く時はこの説明文字列をつけることが推奨されています。

さて、この説明文字列ですが、いろいろとルールがあります。

GNU Emacs Lispリファレンスマニュアル: Documentation Tips

このルールにしたがって、説明文字列が書けているかをチェックしているか、確認するためのマイナーモードが checkdoc-minor-mode です。

checkdoc-minor-mode のキーバインド

checkdoc-minor-mode を有効にすると次のようなキーバインドが有効となります。

C-M-x checkdoc-eval-defun
C-c ? SPC checkdoc-rogue-spaces
C-c ? B checkdoc-ispell-current-buffer
C-c ? C checkdoc-ispell-comments
C-c ? D checkdoc-ispell
C-c ? M checkdoc-ispell-message-text
C-c ? S checkdoc-ispell-start
C-c ? X checkdoc-ispell-defun
C-c ? ` checkdoc-continue
C-c ? b checkdoc-current-buffer
C-c ? c checkdoc-comments
C-c ? d checkdoc
C-c ? e checkdoc-eval-current-buffer
C-c ? m checkdoc-message-text
C-c ? s checkdoc-start
C-c ? x checkdoc-defun
C-c ? ~ dcheckdoc-ispell-continue

と、いろいろありますが 主に使うのが checkdoc で、これは対話的におかしいところにジャンプして修正案まで提示してくれます。aspellが使える環境であれば、 checkdoc-ispell を使うことで、スペルチェックまでしてくれます。

checkdoc-eval-current-bufferは 修正すべき箇所を別バッファにリストアップしてくれます。おかしいところがどれくらいあるか知りたい時には便利かもしれません。

面白いところでは、 C-M-xcheckdoc-eval-defun に上書きされているところでしょうか。 従来の eval-defuncheckdoc の機能を付加してくれています。

英語で書くことが前提なので、なかなか書かずに放置することが多い説明文字列ですが、多くの人に使ってもらおうと思えば、やっぱり書いておいた方がいいなぁとあらためて思いました。