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

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,

16

Railsy mają pewne wytyczne dotyczące dokumentacji API . To prawdopodobnie dobry punkt wyjścia.

— Hank Gay
źródło

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

2

Oto dokumentacja systemu dokumentacji ruby (RDOC)

— jrhicks
źródło