Re: docstring of functions and variables

[TSUCHIYA Masatoshi <tsuchiya@xxxxxxxxxxxxxxxxxxxxxxx>]

>> On Thu, 27 Nov 2003 00:38:03 +0900
>> 「山」== yamaoka@jpl.org (Katsumi Yamaoka) said as follows:

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 で終わらせても最低限の意味が通じる完
山> 全な文 (まあ主語や代名詞の省略が多々ありますが)になるように心掛け
山> ています。

器用な逃げ方ですね．

確かに，1行目が period で終わらないといけないとは書いてませんが，第2文
を普通に解釈したら「最初の行は，関数の意図を説明した1つまたは2つの文か
らなるべきだ」だと思うので，不完全な文は推奨されていないのだと思ってい
ました．

山> でも、ご指摘があった以上は、練り直してみることにしましょう。

いやそこまでしていただかなくとも．

ひょっとして気付いてらっしゃらないのかと思ってメールしただけですから，
山岡さんがそういう convention で作業しようと言うことでしたら，私は反対
しません．

私も，元気なときはまめに説明を書くようにしていますが，変更が大規模にな
ればなるほどサボリ癖が出てしまうので，こういう改善作業は有難いです．

-- 
土屋 雅稔 ( TSUCHIYA Masatoshi )