วิธีเอกสารรหัสทับทิม?

มีการจัดทำรหัสบางอย่างเมื่อบันทึกรหัสทับทิมหรือไม่ ตัวอย่างเช่นฉันมีข้อมูลโค้ดต่อไปนี้:

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 และใช้มันเพื่อสร้างเอกสารของคุณในเครื่องของคุณหากมี

RDoc จะยังคงถูกต้องตามที่ Yard ใช้

รางมีบางส่วนแนวทาง API เอกสาร นั่นอาจเป็นจุดเริ่มต้นที่ดี

คุณสามารถตรวจสอบ TomDoc สำหรับ Ruby - เวอร์ชัน 1.0.0-rc1

http://tomdoc.org/

บัญญัติเป็น RDocมันคล้ายกับที่คุณโพสต์

ดูตัวอย่างในลิงค์ที่ฉันส่งให้คุณ

นี่คือเอกสารสำหรับระบบเอกสารทับทิม (RDOC)