documentation - Lo último en herramientas de documentación de Clojure

javadoc literate-programming

Question

Durante el último año más o menos, he visto varios anuncios en la lista de discusión de Clojure y otros lugares sobre herramientas para documentar el código de Clojure. Estos van desde sistemas completos de programación alfabetizada como Marginalia, y la herramienta que se usa para crear el libro "Clojure in Small Pieces" (o incluso emacs org-mode), hasta soluciones de estilo Javadoc más convencionales como Autodoc, y el mismo Javadoc que según se informa se puede utilizar con Clojure. Una búsqueda en Google revela varios otros, quizás algunos que merecen más atención, y seguramente algunos que son solo utilidades personales para generar documentos. Mi pregunta es, ¿cuáles son las mejores herramientas de documentación, y cuáles son sus fortalezas y debilidades comparativas en función de sus experiencias al usarlas? No he utilizado ninguna herramienta de documentación hasta la fecha, y estoy interesado en experimentar con uno o más.

Answer 1

Realmente me gusta Marginalia si quieres tomar algo como un enfoque de programación alfabetizada. Marginalia atraviesa su código fuente y produce una versión formateada en html con comentarios establecidos junto al código en un texto muy claro. Los comentarios se pueden cambiar de formato, lo que lo convierte en un documento final muy legible. Al revisar el código fuente que he escrito hace un tiempo, me parece Marginalia realmente ayuda. Aquí hay un ejemplo hecho de la fuente Marginalia en sí .

Tenga en cuenta que esto difiere del flujo de trabajo de programación alfabetizado original, donde se escribiría un archivo y se generaría el código fuente a partir de eso. Con Marginalia, usted escribe un archivo de código fuente regular, y es la documentación que se extrae de eso. La salida es similar a lo que uno esperaría de la programación alfabetizada, pero de esta manera todavía se puede esperar resaltar la sintaxis en un editor, sin ningún soporte especial de programación alfabetizada.

Interopera con Leiningen, y creo pastel, aunque yo mismo no lo he intentado.

Answer 2

Si quieres org-babel-clojure completamente, debes darle una mirada a org-babel-clojure . org-bable es una extensión de programación literaria para emacs org-mode.

Si desea usar nrepl, debe agregar lo siguiente a su .emacs:

(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!"))))))

Answer 3

Autodoc es un lugar fácil para comenzar y es lo que producen Clojure core y Clojure contrib .

Fácil de usar con Maven . No estoy seguro de si existen complementos para Leiningen o Cake.

Answer 4

Codox es un generador de documentación más reciente para Clojure.