[Date Prev][Date Next][Thread Prev][][Date Index][Thread Index]

docstring of functions and variables



最近,山岡さんが docstring の見直しを進めてくださっていますが,その差
分に以下のような例がありました.

   (defun w3m-fontify-strike-through ()
  -  "Fontify strike-through characters in this buffer which contains half-dumped data."
  +  "Fontify strike-through characters in the current buffer
  +assuming that halfdump'ed data are contained."
     (when (and w3m-fontify-strike-through

(Info-goto-node "(elisp)Function Documentation") によれば,

info> The first line of the documentation string should stand on its
info> own, because `apropos' displays just this first line.  It should
info> consist of one or two complete sentences that summarize the
info> function's purpose.

となっています.そのため,私はこれまで,多少の不正確さや column のはみ
出しには目をつぶって,概要を先頭の1行に書き,詳細説明が必要な場合は2行
目以降に書くようにしてきました.

そんなに重要な convention ではないと思うので,杓子定規に守る必要はない
でしょうが,ちょっとだけ気になりました.

それから,apropos によって,変数の説明文字列が表示される場合も,やはり
先頭の1行だけが表示されますから,同様の convention が適用されるだろう
と思います.

-- 
土屋 雅稔 ( TSUCHIYA Masatoshi )