Lo último en herramientas de documentación de Clojure

Durante el último año o así, 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.Lo último en herramientas de documentación de Clojure

Fuente

2011-03-17 rplevy

Al igual que un punto a destacar, Marginalia no es una herramienta de programación literaria completa. En muchos sentidos, facilita un estilo alfabetizado, pero de ninguna manera comprende cómo lidiar con los comentarios del código fuera de orden, como el sistema utilizado en "Clojure in Small Pieces". org-babel-clojure, o el CWEB de Knuth. Es solo una buena herramienta para facilitar la lectura de códigos. – fogus

Parece que tanto Autodoc como Marginalia están dirigidos por cadenas de documentos, y ambos tienen una buena integración con Leiningen, pero la principal diferencia es que Marginalia genera una producción más rica, mientras que Autodoc es más básico. ¡Gracias! – rplevy

Me gusta mucho Marginalia si quiere 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. Here's an example made from the Marginalia source itself.

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 no lo he intentado yo mismo.

Fuente

2011-03-17 04:09:44

Me gusta la marginalia también. Un problema es que no constituye una muy buena referencia indexada. Por otra parte, ese no es realmente su propósito. – apg

@Andrew tiene algún tipo de indexación en los planes. :-) – fogus

@fogus - ¡oh limpio! eso será extremadamente útil. – apg

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.

Fuente

2011-03-17 03:57:44

Mirando el enlace provisto para [Autodoc] (http://tomfaulhaber.github.com/autodoc/), hay una sección sobre el complemento lein para autodoc: [Autodoc de construcción con Leiningen] (http: //tomfaulhaber.github. com/autodoc/# building_with_leiningen) –

Mi proyecto no utiliza una clase principal 'clojure.main' y autodoc rescata debido a esto:' Error: no se pudo encontrar o cargar la clase principal clojure.main'. No he podido encontrar una manera de especificar mi propia clase principal en un Maven POM. –

Si quiere aprender completamente, debe darle un vistazo a org-babel-clojure. org-bable es una extensión de programación literaria para emacs org-mode.

Si desea utilizar nrepl la siguiente debe añadirse 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!"))))))

Fuente

2011-03-17 06:19:49 mac

Ahora que swank-clojure ha quedado en desuso en favor de nrepl, ¿hay alguna actualización o alternativa a org-babel-clojure? Estoy investigando noweb para LP, pero sería genial tener una respuesta durante la escritura/desarrollo. –

org-babel-clojure funciona muy bien nrepl. He editado mi respuesta anterior para reflejar mi uso actual. – mac

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

Fuente

2012-08-10 20:44:26 cderoove

Atestiguaré esto como una buena alternativa. Marginalia es impresionante por presentar el código junto con los documentos, pero tiene un poco demasiado de "personalidad", lo que me parece una distracción. Codox supuestamente también tiene soporte para analizar html en línea y, posiblemente, rebaja, pero, irónicamente, la documentación es demasiado escasa para que la descubra (¡y ni siquiera la salida codox!) –

Lo último en herramientas de documentación de Clojure

Respuesta

Cuestiones relacionadas