コード内ドキュメント

コード内に自動生成できるフォーマットでドキュメントを書くべきなのは賛成です。開発の際に有用だと思うからです。それでも、ライブラリ「ユーザ」には、自動生成した文書 *だけ* を見せるようにするべきだろうという考えです。ソースを見ろというのでは無くです。

ただし、経験上、自動生成した文書だけを読んでよくわかるようなコメントを書くのは結構面倒でもあり、難しい面もあります。細かいところの矛盾や不具合を無いように整えようとする場合は特に。コメントが長くなり過ぎたりもしがちですし。あと、英語でコメント書くと、日本語版はどうするのという問題もあります。

それだったら、別途チュートリアルや仕様書をちゃんと書いて、自動生成ドキュメントが少々荒くても見逃してもらえるようにする方が、簡単だったりするのではと感じていたりします。