Stato dell'Arte per Clojure Strumenti di documentazione [chiusa]

Question

Nel corso dell'ultimo anno o giù di lì che ho visto diversi annunci sulla lista di discussione Clojure e altri luoghi sugli strumenti per la documentazione del codice Clojure. Questi vanno dal pieno su sistemi di programmazione alfabetizzati come Marginalia, e lo strumento utilizzato per creare il libro "Clojure in Small Pieces" (o anche emacs org-mode), alle soluzioni Javadoc in stile più convenzionali come Autodoc, e Javadoc stessa che come riferito può essere utilizzato con Clojure. Una ricerca su Google si trasforma fino vari altri, forse un paio che meritano più attenzione, e sicuramente alcuni che sono solo le utilità personali per la generazione di documenti. La mia domanda è: quali sono i migliori strumenti di documentazione, e quali sono i loro punti di forza e di debolezza di confronto, sulla base di esperienze che li utilizzano? Non ho usato nessun strumenti di documentazione fino ad oggi, e sono interessato a sperimentare con uno o più.

Answer 1

Mi piace molto Marginalia se si vuole prendere qualcosa di simile a un approccio di programmazione letterata. Marginalia attraversa il codice sorgente, e produce una versione in formato HTML con i commenti set accanto a codice in un testo molto chiaro. I commenti possono essere formattati Markdown, rendendo per un documento finale molto leggibile. Nel rivedere il codice sorgente che ho scritto qualche tempo fa, trovo Marginalia aiuta veramente. Ecco un esempio realizzato dalla fonte Marginalia sé .

Si noti che questo è diverso dal flusso di lavoro di programmazione letterata originale, in cui si potrebbe scrivere un codice del file e la fonte è generato da questo. Con Marginalia, si scrive un file di codice sorgente regolare, ed è la documentazione che ha tirato fuori questo. L'output è simile a quello che ci si potrebbe aspettare dalla programmazione leggere e scrivere, ma in questo modo si può ancora aspettare di evidenziazione della sintassi in un editor, senza alcun supporto speciale di programmazione letterata.

Si interagisce con Leiningen, e credo che la torta, anche se non ho provato io stesso.

Answer 2

Autodoc è un posto facile per iniziare ed è ciò che Clojure nucleo e Clojure contrib prodotti .

Facile da usare con Maven . Non sono sicuro se esisto plugin per Leiningen o torta.

Answer 3

Codox è una più recente generatore di documentazione per Clojure.

Answer 4

Se si vuole andare letterato completamente si dovrebbe dare org-babel-clojure uno sguardo. org-bable è un'estensione programmazione istruita emacs org-mode.

Se si desidera utilizzare nrepl il seguente dovrebbe essere aggiunto ai tuoi .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!"))))))