Estado del arte para herramientas de documentación de Clojure [cerrado

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 Clojure. Estos van desde sistemas de programación alfabetizados completos como Marginalia y la herramienta que se utiliza para crear el libro "Clojure en piezas pequeñas" (o incluso emacs en modo de organización), hasta soluciones más convencionales de estilo Javadoc como AutoDoc y Javadoc que en sí mismo que en sí mismo que en sí mismo que en sí mismo lo que Según se informa, se puede usar con Clojure. Una búsqueda en Google aparece varios otros, quizás algunos que merecen más atención y, por supuesto, algunas 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 basadas en sus experiencias que las usan? No he utilizado ninguna herramienta de documentación hasta la fecha, y estoy interesado en experimentar con uno o más.

Answer 1

de verdad me gusta Nota marginal Si quieres adoptar algo como un enfoque de programación alfabetizado. Marginalia atraviesa su código fuente y produce una versión formateada HTML con comentarios establecidos junto al código en un texto muy claro. Los comentarios se pueden formatear Markdown, lo que lo convierte en un documento final muy legible. Al revisar el código fuente que he escrito hace algún tiempo, encuentro que Marginalia realmente ayuda. Aquí hay un ejemplo hecho con la fuente de Marginalia en sí misma.

Tenga en cuenta que esto difiere del flujo de trabajo de programación alfabetizado original, donde escribiría un archivo y el código fuente se genera a partir de eso. Con Marginalia, 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 podría esperar de la programación alfabetizada, pero de esta manera aún puede esperar resaltar sintaxis en un editor, sin ningún soporte de programación de alfabetización especial.

Interopera con Leiningen, y creo que Cake, aunque no lo he probado yo mismo.

Answer 2

Autodoc es un lugar fácil para comenzar y es lo que Clojure centro y clojure contribuir producir.

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

Answer 3

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

Answer 4

Si quieres ser completamente alfabetizado, debes dar org-babel-clocejure una mirada. Org-Bable es una extensión de programación alfabetizada al modo ORG EMACS.

Si desea usar NREPL, se debe agregar lo siguiente a sus .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!"))))))