1. ホーム
  2. ルビー

[解決済み】Rubyのコードを文書化する方法は?

2022-04-10 21:16:54

質問

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プロセッサは、あなたのドキュメントを見つけ出し、そこから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)