루비 코드를 문서화하는 방법?

루비 코드를 문서화 할 때 특정 코드 규칙이 있습니까? 예를 들어 다음 코드 스 니펫이 있습니다.

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)

RDoc 사용 을 적극 권장 합니다. 거의 표준입니다. 코드 주석을 쉽게 읽을 수 있으며 프로젝트에 대한 웹 기반 문서를 쉽게 만들 수 있습니다.

명시된 바와 같이 RDoc을 알게 될 것을 제안합니다. 그러나 인기있는 YARD A Ruby Document 도구도 무시하지 마십시오 . Ruby 용으로 온라인에서 볼 수있는 많은 문서는 Yard를 사용합니다. RVM은 Yard를 알고 있으며 사용 가능한 경우 시스템에서 문서를 생성하는 데 사용합니다.

Yard가 사용하므로 RDoc은 여전히 ​​필요합니다.

Rails에는 몇 가지 API 문서 지침이 있습니다. 아마도 좋은 출발점이 될 것입니다.

TomDoc for Ruby-버전 1.0.0-rc1을 확인할 수도 있습니다.

http://tomdoc.org/

표준은 RDoc 이며 게시 한 것과 매우 유사합니다.

내가 보낸 링크의 샘플 섹션을 참조하십시오

다음은 루비 문서 시스템 (RDOC)에 대한 문서입니다.