Rubyコードを文書化するには？

Question

ルビコードを文書化する際に特定のコード規約がありますか？たとえば、私は次のコードスニペットを持っています：

require 'open3' 

module ProcessUtils 

    # Runs a subprocess and applies handlers for stdout and stderr 
    # Params: 
    # - command: command line string to be executed by the system 
    # - outhandler: proc object that takes a pipe object as first and only param (may be nil) 
    # - errhandler: proc object that takes a pipe object as first and only param (may be nil) 
    def execute_and_handle(command, outhandler, errhandler) 
    Open3.popen3(command) do |_, stdout, stderr| 
     if (outhandler) 
     outhandler.call(stdout) 
     end 
     if (errhandler) 
     errhandler.call(stderr) 
     end 
    end 
    end 
end 

これは大丈夫ですが、おそらくより優れた/優れたドキュメントの実践がありますか？

Answer 1

RDocプロセッサのドキュメントを対象にする必要があります.Dococプロセッサはドキュメントを見つけてHTMLを生成できます。あなたは正しい場所にあなたのコメントを入れましたが、RDocがどのようにフォーマットするのかを知るタグの種類については、RDoc documentationをご覧ください。次のようにそのために、私はあなたのコメントを再フォーマットしたい：ここ

# Runs a subprocess and applies handlers for stdout and stderr 
    # Params: 
    # +command+:: command line string to be executed by the system 
    # +outhandler+:: +Proc+ object that takes a pipe object as first and only param (may be nil) 
    # +errhandler+:: +Proc+ object that takes a pipe object as first and only param (may be nil) 

Answer 2

標準名はRDocです。あなたが投稿したものと非常に似ています。

私はあなたに

Answer 3

を送ったリンク上のサンプルを参照してください、私は非常にはRDocを使用してお勧めします。それはかなり標準です。コードコメントを読むのは簡単で、プロジェクト用のWebベースのドキュメントを簡単に作成することができます。

Answer 4

レール数はAPI Documentation Guidelinesです。それはおそらく良い出発点です。

Answer 5

がruby documentation system (RDOC)

Answer 6

のドキュメントであるあなたはまた、RubyのためTomDocを確認することができます - バージョン1.0.0-RC1。

http://tomdoc.org/

Answer 7

私が記載されているとしてのRDocを知ってもらうことをお勧め。しかし、非常に人気のあるYARD A Ruby Documentツールも無視しないでください。 Rubyのオンラインで表示されるドキュメントの多くは、Yardを使用しています。 RVMはYardを認識し、使用可能な場合はマシン上でドキュメントを生成するためにYVMを使用します。

ヤードが使用するように、RDocはまだ必要です。