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

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

16

Rails verfügt über einige Richtlinien zur API-Dokumentation . Das ist wahrscheinlich ein guter Ausgangspunkt.

— Hank Gay
quelle

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

2

Hier ist die Dokumentation für das Ruby Documentation System (RDOC)

— jrhicks
quelle