Wie dokumentiere ich Ruby-Code?

201

Gibt es bestimmte Codekonventionen bei der Dokumentation von Ruby-Code? Zum Beispiel habe ich das folgende Code-Snippet:

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

Diese Vermutung ist in Ordnung, aber vielleicht gibt es bessere / überlegene Dokumentationspraktiken?

ruby StackedCrooked
quelle
shop.oreilly.com/product/9780596516178.do hat ein schönes kleines Beispiel im Quellcode. Schauen Sie in Kapitel 2 Liste. Es ist ungefähr wie die Antwort hier. Ich habe mit rdoc gespielt, nur um den Quellcode anzuzeigen. Sie können Ihre Dateierweiterung wie my_code.rb in my_code.rb.txt ändern und dann rdoc darauf ausführen. > rdoc my_code.rb.txt dann spielt es keine Rolle für Klassen und Module, da rdoc sowieso HTML dafür rendert. Viel Spass damit.
Douglas G. Allen

Antworten:

198

Sie sollten Ihre Dokumentation auf den RDoc-Prozessor ausrichten, der Ihre Dokumentation finden und daraus HTML generieren kann. Sie haben Ihren Kommentar dafür an der richtigen Stelle platziert, sollten sich jedoch die RDoc-Dokumentation ansehen, um zu erfahren, welche Arten von Tags RDoc formatieren kann. Zu diesem Zweck würde ich Ihren Kommentar wie folgt neu formatieren:

  # 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
quelle
Wie soll ich dokumentieren, dass die Parameter outhandler und errhandler möglicherweise Null sind?
StackedCrooked
10
Die Annotationen von YARD sind zwar leistungsfähiger, aber bis sie in der Standard-Ruby-Distribution anstelle von RDoc enthalten sind, sind die Annotationen nicht der Standard.
Ken Bloom
Der RDoc-Link ist defekt. Versuchen Sie Folgendes : github.com/ruby/rdoc . Ich werde darum bitten, die Antwort zu bearbeiten, wenn alle mit diesem Link zufrieden sind.
Jordan Stewart
27

Ich würde die Verwendung von RDoc sehr empfehlen . Es ist so ziemlich der Standard. Es ist einfach, die Codekommentare zu lesen, und Sie können auf einfache Weise eine webbasierte Dokumentation für Ihr Projekt erstellen.

Topher Fangio
quelle
24

Ich würde vorschlagen, RDoc wie angegeben kennenzulernen. Aber ignorieren Sie auch nicht das sehr beliebte Tool YARD A Ruby Document . Ein Großteil der Dokumentation, die Sie online für Ruby sehen, verwendet Yard. RVM kennt Yard und verwendet es zum Generieren Ihrer Dokumentation auf Ihrem Computer, falls verfügbar.

RDoc wäre weiterhin erforderlich, da Yard es verwendet.

vgoff
quelle
1
Nachdem ich hauptsächlich C ++, Java, Scala und PHP verwendet habe, finde ich die @tagNotation sehr vertraut.
Doub1ejack
1
Es ist vier Jahre her und YARD hat sich stark weiterentwickelt. Schade, dass YARD immer noch nicht in Ruby enthalten ist. (Übrigens akzeptiert die YARD-Homepage HTTPS.)
Franklin Yu
1
YARD scheint leichter zu sein als RDoc! Danke :)
Constantin De La Roche
9

Sie können auch TomDoc für Ruby - Version 1.0.0-rc1 überprüfen.

http://tomdoc.org/

onurozgurozkan
quelle
FWIW, dieser ist im GitHub Style Guide angegeben - github.com/styleguide/ruby
Michael Easter
Vielen Dank, Tomdoc scheint eine gute Quelle für bewährte Methoden zu sein, wenn es darum geht, Ruby-Code zu dokumentieren. Beantwortet das "Wie" und "Warum", das anscheinend in der rdoc-Dokumentation fehlt.
Michael Renner
TomDoc wurde nicht auf dem neuesten Stand gehalten. Letzte Verpflichtung war Mai 2012.
Maasha
1
@maasha Bis 2017 glaube ich, dass die beste Wahl neben einfachem RDoc YARD wäre, jetzt, wo es den Inhalt analysiert und einige ausgefallene Hyperlinks zu Klassen und Methoden erstellt.
Franklin Yu
2

Der Kanon ist RDoc. Er ist dem von Ihnen geposteten sehr ähnlich.

Siehe den Beispielabschnitt unter dem Link, den ich Ihnen gesendet habe

OscarRyz
quelle