Bagaimana cara mendokumentasikan kode Ruby?

201

Apakah ada konvensi kode tertentu saat mendokumentasikan kode ruby? Misalnya saya memiliki cuplikan kode berikut:

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

Tebakan ini tidak apa-apa, tapi mungkin ada praktik dokumentasi yang lebih baik / unggul?

ruby

— StackedCrooked
sumber

shop.oreilly.com/product/9780596516178.do memiliki contoh kecil yang bagus dalam kode sumber. Lihat di bab 2 daftar. Ini tentang seperti jawabannya di sini. Saya telah bermain dengan rdoc hanya untuk menunjukkan kode sumber. Anda dapat membuat ekstensi file Anda seperti my_code.rb ke my_code.rb.txt dan kemudian jalankan rdoc di atasnya. > rdoc my_code.rb.txt maka itu tidak masalah dengan kelas dan modul karena rdoc akan membuat html untuk itu. Bersenang-senanglah dengan itu.

— Douglas G. Allen

198

Anda harus menargetkan dokumentasi Anda untuk prosesor RDoc, yang dapat menemukan dokumentasi Anda dan menghasilkan HTML darinya. Anda telah meletakkan komentar Anda di tempat yang tepat untuk itu, tetapi Anda harus melihat pada dokumentasi RDoc untuk mempelajari tentang jenis-jenis tag yang RDoc tahu cara memformat. Untuk itu, saya akan memformat ulang komentar Anda sebagai berikut:

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

— Ken Bloom
sumber

Bagaimana saya harus mendokumentasikan bahwa parameter outhandler dan errhandler mungkin nihil?

— StackedCrooked

10

Anotasi YARD mungkin lebih kuat, tetapi sampai dimasukkan dalam distribusi Ruby standar alih-alih RDoc, anotasinya bukan standar.

— Ken Bloom

Tautan RDoc rusak coba ini: github.com/ruby/rdoc . Saya akan meminta untuk mengedit jawaban jika semua orang senang dengan tautan itu.

— Jordan Stewart

27

Saya akan sangat menyarankan menggunakan RDoc . Cukup standar. Sangat mudah untuk membaca komentar kode, dan memungkinkan Anda untuk dengan mudah membuat dokumentasi berbasis web untuk proyek Anda.

— Topher Fangio
sumber

24

Saya akan menyarankan untuk mengenal RDoc seperti yang dinyatakan. Tetapi jangan abaikan juga alat YARD A Ruby Document yang sangat populer . Banyak dokumentasi yang akan Anda lihat online untuk Ruby menggunakan Yard. RVM mengenal Yard dan menggunakannya untuk membuat dokumentasi Anda di mesin Anda jika tersedia.

RDoc masih diperlukan, seperti Yard menggunakannya.

— vgoff
sumber

1

Setelah menggunakan sebagian besar C ++, Java, Scala dan PHP, saya menemukan @tagnotasi yang sangat akrab.

— doub1ejack

1

Sudah empat tahun dan YARD telah berkembang pesat. Sangat disayangkan bahwa YARD masih belum termasuk dalam Ruby. (Omong-omong, beranda YARD menerima HTTPS.)

— Franklin Yu

1

HALAMAN tampaknya lebih ringan daripada RDoc! Terima kasih :)

— Constantin De La Roche

16

Rails memiliki beberapa Pedoman Dokumentasi API . Itu mungkin titik awal yang baik.

— Hank Gay
sumber

9

Anda juga dapat memeriksa TomDoc untuk Ruby - Versi 1.0.0-rc1.

http://tomdoc.org/

— onurozgurozkan
sumber

FWIW, yang ini dispesifikasikan dalam panduan gaya GitHub - github.com/styleguide/ruby

— Michael Easter

Terima kasih, tomdoc tampaknya menjadi sumber yang baik untuk praktik terbaik saat ini dalam hal mendokumentasikan kode ruby. Menjawab "bagaimana" dan "mengapa" yang tampaknya hilang dari dokumentasi rdoc.

— Michael Renner

TomDoc belum diperbarui. Komit terakhir adalah Mei 2012.

— maasha

1

@maasha Pada 2017, saya yakin taruhan terbaik selain RDoc biasa adalah YARD, sekarang ia mem-parsing konten dan membuat beberapa hyperlink mewah ke kelas dan metode.

— Franklin Yu

2

Kanonik RDoc sangat mirip dengan yang Anda posting.

Lihat bagian sampel pada tautan yang saya kirimkan kepada Anda

— OscarRyz
sumber

2

Berikut ini adalah dokumentasi untuk sistem dokumentasi ruby (RDOC)

— Jrhicks
sumber