Stand der Technik für Clojure -Dokumentationsinstrumente [geschlossen

Question

Im letzten Jahr habe ich verschiedene Ankündigungen auf der Clojure -Diskussionsliste und an anderen Orten zu Tools zum Dokumentieren von Clojure -Code gesehen. Diese reichen von voll ausgelösten Programmiersystemen wie Marginalia und dem Werkzeug, das zum Erstellen des Buches "Clojure in kleinen Stücken" (oder sogar EMACS-Org-Mode) bis hin zu herkömmlichen Lösungen im Javadoc-Stil wie Autodoc und Javadoc selbst erstellt wird. Berichten zufolge können mit Clojure verwendet werden. Eine Google -Suche taucht verschiedene andere auf, vielleicht einige, die mehr Aufmerksamkeit verdienen, und sicher einige, die nur persönliche Dienstprogramme für die Generierung von Dokumenten sind. Meine Frage ist, was sind die besten Dokumentationsinstrumente und welche vergleichenden Stärken und Schwächen basieren auf Ihren Erfahrungen, die sie verwenden? Ich habe bisher keine Dokumentationstools verwendet und bin daran interessiert, mit einem oder mehreren zu experimentieren.

Answer 1

ich mag wirklich Marginalia Wenn Sie so etwas wie einen gebildeten Programmieransatz verfolgen möchten. Marginalia durchquert Ihren Quellcode und erstellt eine HTML -Formatierung mit Kommentaren, die neben Code in einem sehr klaren Text festgelegt sind. Kommentare können angegeben werden, um ein sehr lesbares endgültiges Dokument zu erzielen. Bei der Überprüfung von Quellcode, den ich vor einiger Zeit geschrieben habe, finde ich Marginalia wirklich hilft. Hier ist ein Beispiel aus der Marginalia -Quelle selbst.

Beachten Sie, dass dies vom ursprünglichen Programmier -Workflow von Literate -Programmierungen unterscheidet, in dem Sie eine Datei schreiben und der Quellcode daraus generiert wird. Mit Marginalia schreiben Sie eine reguläre Quellcode -Datei und es ist die Dokumentation, die daraus herausgezogen wird. Die Ausgabe ähnelt dem, was man von der Lehrerprogrammierung erwarten könnte. Auf diese Weise können Sie jedoch immer noch die Syntax -Hervorhebung in einem Editor erwarten, ohne dass eine spezielle Programmierunterstützung für den gebildeten Literat ist.

Es arbeitet mit Leiningen zusammen und ich glaube Kuchen, obwohl ich das selbst nicht ausprobiert habe.

Answer 2

Autodoc ist ein einfacher Ort zum Starten und ist das, was Clojure Ader und Clojure beitragen produzieren.

Einfach zu bedienen mit Maven. Ich bin mir nicht sicher, ob Plugins für Leiningen oder Kuchen vorhanden sind.

Answer 3

Codox ist ein neuerer Dokumentationsgenerator für Clojure.

Answer 4

Wenn Sie voll ausgelöst werden möchten, sollten Sie geben Org-Babel-Clojure ein Blick. Org-Bable ist eine gebildete Programmiererweiterung des EMACS-Org-Mode.

Wenn Sie NREPL verwenden möchten, sollte dies zu Ihren .Emacs hinzugefügt werden:

(defun org-babel-execute:clojure (body params)
  "Execute a block of Clojure code with Babel."
  (let ((result-plist (nrepl-send-string-sync (org-babel-expand-body:clojure body params) nrepl-buffer-ns))
        (result-type  (cdr (assoc :result-type params))))
    (org-babel-script-escape
     (cond ((eq result-type 'value)  (plist-get result-plist :value))
           ((eq result-type 'output) (plist-get result-plist :value))
            (t                        (message "Unknown :results type!"))))))