Re: docstring of functions and variables

[Katsumi Yamaoka <yamaoka@xxxxxxx>]

>>>>> In [emacs-w3m : No.06135] 
>>>>>	TSUCHIYA Masatoshi <tsuchiya@pine.kuee.kyoto-u.ac.jp> wrote:

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

>   +  "Fontify strike-through characters in the current buffer
>   +assuming that halfdump'ed data are contained."

実は他にもあるんですが、

> (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.

一行目が period で終わっていなければならないというルールは無いよ
うに見えたので、その行を period で終わらせても最低限の意味が通じ
る完全な文 (まあ主語や代名詞の省略が多々ありますが) になるように
心掛けています。でも、ご指摘があった以上は、練り直してみることに
しましょう。

[...]

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

それが一番重要です。
-- 
Katsumi Yamaoka <yamaoka@jpl.org>