docstring of functions and variables

[TSUCHIYA Masatoshi <tsuchiya@xxxxxxxxxxxxxxxxxxxxxxx>]

最近，山岡さんが 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 )