루비 코드를 어떻게 문서화합니까?

루비 코드를 어떻게 문서화합니까?

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

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

이는 괜찮지만, 더 나은/우수한 문서 작성 관행이 있을 수 있습니까?

문서를 찾아 HTML을 생성할 수 있는 RDoc 프로세서를 대상으로 문서를 지정해야 합니다.이에 대한 의견을 올바른 위치에 입력했지만 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에 대해 알아가는 것을 제안합니다.그러나 매우 인기 있는 YARDA Ruby Document 도구도 무시하지 마십시오.Ruby에 대해 온라인에서 볼 수 있는 많은 문서들은 Yard를 사용합니다. RVM은 Yard를 알고 있으며 사용 가능한 경우 컴퓨터에서 문서를 생성하는 데 사용합니다.

RDoc은 Yard가 사용하는 것처럼 여전히 필요합니다.

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

또한 TomDoc에서 Ruby - 여전히 버전 1.0.0-rc1(19.09.2022 기준)을 확인할 수 있습니다.

표준 RDocit는 당신이 게시한 것과 매우 유사합니다.

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

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

언급URL : https://stackoverflow.com/questions/1681467/how-to-document-ruby-code