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

Rubyコードを文書化するときに特定のコード規約はありますか？たとえば、次のコードスニペットがあります。

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

これは大丈夫だと思いますが、おそらくより優れた/優れた文書化の方法がありますか？

RDocプロセッサのドキュメントをターゲットにする必要があります。RDocプロセッサは、ドキュメントを見つけてそこからHTMLを生成できます。コメントを適切な場所に配置しましたが、RDocがフォーマット方法を知っているタグの種類については、RDocのドキュメントを参照してください。そのために、コメントを次のように再フォーマットします。

  # 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)

RDocの使用を強くお勧めします。それはほとんど標準です。コードのコメントを読みやすく、プロジェクトのWebベースのドキュメントを簡単に作成できます。

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

Yardが使用しているため、RDocは引き続き必要です。

RailsにはいくつかのAPIドキュメントガイドラインがあります。それはおそらく良い出発点です。

TomDoc for Ruby-バージョン1.0.0-rc1を確認することもできます。

http://tomdoc.org/

正規の RDocは、投稿したものとよく似ています。

送信したリンクのサンプルセクションをご覧ください

これは、rubyドキュメントシステム（RDOC）のドキュメントです。