Come documentare il codice Ruby?

201

Ci sono alcune convenzioni sul codice quando si documenta il codice ruby? Ad esempio ho il seguente frammento di codice:

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

Supponiamo che vada bene, ma forse ci sono pratiche di documentazione migliori / superiori?

ruby

— StackedCrooked
fonte

shop.oreilly.com/product/9780596516178.do ha un piccolo esempio nel codice sorgente. Guarda nell'elenco del capitolo 2. È come la risposta qui. Ho giocato con rdoc solo per mostrare il codice sorgente. È possibile rendere l'estensione del file simile a my_code.rb a my_code.rb.txt e quindi eseguire rdoc su di esso. > rdoc my_code.rb.txt, quindi non importerà su classi e moduli perché rdoc renderà comunque html per esso. Divertiti con esso.

— Douglas G. Allen,

198

Dovresti indirizzare la tua documentazione per il processore RDoc, che può trovare la tua documentazione e generare HTML da essa. Hai messo il tuo commento nel posto giusto per quello, ma dovresti dare un'occhiata alla documentazione RDoc per conoscere i tipi di tag che RDoc sa come formattare. A tal fine, riformattarei il tuo commento come segue:

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

Come devo documentare che i parametri outhandler e errhandler potrebbero essere nulli?

— StackedCrooked

10

Le annotazioni di YARD possono essere più potenti, ma fino a quando non sono incluse nella distribuzione standard di Ruby anziché in RDoc, le sue annotazioni non sono lo standard.

— Ken Bloom,

Il collegamento RDoc è interrotto provare questo: github.com/ruby/rdoc . Chiederò di modificare la risposta se tutti sono soddisfatti di quel link.

— Jordan Stewart,

27

Consiglio vivamente di usare RDoc . È praticamente lo standard. È facile leggere i commenti sul codice e consente di creare facilmente documentazione basata sul Web per il progetto.

— Topher Fangio
fonte

24

Suggerirei di conoscere RDoc come indicato. Ma non ignorare anche il famoso strumento YARD A Ruby Document . Molta della documentazione che vedrai online per Ruby utilizza Yard. RVM conosce Yard e lo utilizza per generare la documentazione sulla macchina, se disponibile.

RDoc sarebbe ancora richiesto, poiché Yard lo usa.

— vgoff
fonte

1

Avendo usato principalmente C ++, Java, Scala e PHP, trovo la @tagnotazione molto familiare.

— doub1ejack il

1

Sono passati quattro anni e YARD si è evoluto notevolmente. È un peccato che YARD non sia ancora incluso in Ruby. (A proposito, la homepage di YARD accetta HTTPS.)

— Franklin Yu,

1

YARD sembra essere più leggero di RDoc! Grazie :)

— Constantin De La Roche,

16

Rails ha alcune linee guida per la documentazione API . Questo è probabilmente un buon punto di partenza.

— Hank Gay
fonte

9

Puoi anche controllare TomDoc per Ruby - Versione 1.0.0-rc1.

http://tomdoc.org/

— onurozgurozkan
fonte

FWIW, questo è specificato nella guida di stile GitHub - github.com/styleguide/ruby

— Michael Easter

Grazie, tomdoc sembra essere una buona fonte per le migliori pratiche attuali quando si tratta di documentare il codice ruby. Risponde al "come" e al "perché" che apparentemente mancano nella documentazione di rdoc.

— Michael Renner,

TomDoc non è stato aggiornato. L'ultimo commit è stato a maggio 2012.

— Maasha,

1

@maasha Entro il 2017 credo che la migliore scommessa oltre al semplice RDoc sarebbe YARD, ora che analizza il contenuto e crea alcuni collegamenti ipertestuali a classi e metodi.

— Franklin Yu,

2

Il canonico è RDoc , è molto simile a quello che hai pubblicato.

Vedi la sezione di esempio sul link che ti ho inviato

— OscarRyz
fonte

2

Ecco la documentazione per il sistema di documentazione ruby (RDOC)

— jrhicks
fonte