Jak udokumentować kod Ruby?

201

Czy istnieją pewne konwencje kodu podczas dokumentowania kodu ruby? Na przykład mam następujący fragment kodu:

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

To chyba w porządku, ale może istnieją lepsze / lepsze praktyki dokumentacyjne?

ruby StackedCrooked
źródło
shop.oreilly.com/product/9780596516178.do ma ładny mały przykład w kodzie źródłowym. Spójrz w wykazie rozdziału 2. Tutaj chodzi o odpowiedź. Grałem z rdoc tylko po to, żeby pokazać kod źródłowy. Możesz zmienić rozszerzenie pliku na mój_kod.rb na mój_kod.rb.txt, a następnie uruchomić na nim program rdoc. > rdoc my_code.rb.txt, to nie będzie miało znaczenia dla klas i modułów, ponieważ rdoc i tak wyświetli dla niego html. Baw się dobrze.
Douglas G. Allen

Odpowiedzi:

198

Powinieneś skierować swoją dokumentację na procesor RDoc, który może znaleźć twoją dokumentację i wygenerować z niej HTML. Umieściłeś swój komentarz we właściwym miejscu, ale powinieneś zajrzeć do dokumentacji RDoc, aby dowiedzieć się o rodzajach tagów, które RDoc wie, jak formatować. W tym celu sformatuję Twój komentarz w następujący sposób:

  # 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
źródło
Jak mam udokumentować, że parametry modułu przenoszącego i modułu błędów mogą być zerowe?
StackedCrooked
10
Adnotacje YARD mogą być mocniejsze, ale dopóki nie zostaną zawarte w standardowej dystrybucji Ruby zamiast RDoc, jej adnotacje nie są standardowe.
Ken Bloom
Link RDoc jest zepsuty, spróbuj tego: github.com/ruby/rdoc . Poproszę o edycję odpowiedzi, jeśli wszyscy będą zadowoleni z tego linku.
Jordan Stewart
27

Chciałbym bardzo sugerować użyciu rdoc . To jest prawie standard. Czytanie komentarzy do kodu jest łatwe i umożliwia łatwe tworzenie dokumentacji internetowej dla twojego projektu.

Topher Fangio
źródło
24

Sugerowałbym, aby poznać RDoc, jak stwierdzono. Ale nie ignoruj ​​również bardzo popularnego narzędzia YARD A Ruby Document . Wiele dokumentacji, którą zobaczysz online dla Ruby, używa Yard. RVM zna Yard i używa go do generowania dokumentacji na komputerze, jeśli jest ona dostępna.

RDoc nadal byłby wymagany, ponieważ Yard go używa.

vgoff
źródło
1
Używając głównie C ++, Java, Scali i PHP uważam @tagnotację za bardzo znaną.
doub1ejack
1
Minęły cztery lata, a YARD bardzo ewoluował. Szkoda, że ​​YARD nadal nie jest uwzględniony w Ruby. (Nawiasem mówiąc, strona główna YARD akceptuje HTTPS.)
Franklin Yu
1
YARD wydaje się być lżejszy niż RDoc! Dzięki :)
Constantin De La Roche,
9

Możesz także sprawdzić TomDoc pod kątem Ruby - wersja 1.0.0-rc1.

http://tomdoc.org/

onurozgurozkan
źródło
FWIW, ten jest określony w przewodniku po stylu GitHub - github.com/styleguide/ruby
Michael Easter
Dzięki, tomdoc wydaje się być dobrym źródłem najlepszych praktyk w zakresie dokumentowania kodu ruby. Odpowiedzi na pytanie „jak” i „dlaczego”, które najwyraźniej brakuje w dokumentacji rdoc.
Michael Renner
TomDoc nie był na bieżąco. Ostatnie zatwierdzenie miało miejsce w maju 2012 r.
maasha
1
@maasha Do 2017 roku uważam, że najlepszym rozwiązaniem poza zwykłym RDoc będzie YARD, teraz, gdy analizuje zawartość i tworzy fantazyjne hiperłącza do klas i metod.
Franklin Yu
2

Kanoniczny jest RDoc , jest bardzo podobny do tego, który opublikowałeś.

Zobacz przykładową sekcję linku, który ci wysłałem

OscarRyz
źródło