Au cours de la dernière année, j'ai vu plusieurs annonces sur le Clojure liste de discussion et d'autres lieux sur les outils de la documentation Clojure code. Celles-ci vont de plein-sur lettré systèmes de programmation comme les notes marginales, et l'outil utilisé pour créer le livre "Clojure en Petits Morceaux" (ou même emacs org-mode), à plus conventionnelle de Javadoc solutions comme Autodoc, et Javadoc lui-même qui aurait peut être utilisé avec Clojure. Une recherche sur google tourne beaucoup d'autres, peut-être quelques-uns qui méritent plus d'attention, et pour sûr que certains qui sont juste des personnels des utilitaires pour la génération de documents. Ma question est quels sont les meilleurs outils de documentation, et quelles sont leurs forces et faiblesses en fonction de votre expérience de les utiliser? Je n'ai pas utilisé l'un des outils de documentation à ce jour, et je suis intéressé à expérimenter avec un ou plusieurs.
Réponses
Trop de publicités?
J'aime vraiment Marginalia si vous voulez prendre quelque chose comme un lettré approche de la programmation. Marginalia traverse votre code source, et produit un format html version avec commentaires, situé à côté de code dans un très clair dans le texte. Les commentaires peuvent être markdown formaté, ce qui rend très lisible du document final. Lors de l'examen de code source que j'ai écrit il y a quelques temps, je trouve les notes marginales aide vraiment. Voici un exemple réalisé à partir de la Marginalia de la source elle-même.
Notez que ce qui diffère de l'original lettré de programmation des flux de travail, où vous pouvez écrire un fichier et le code source est généré à partir de ce. Avec Marginalia, vous écrivez régulièrement un fichier de code source, et c'est la documentation qui est sorti de cette. La sortie est similaire à ce que l'on pourrait attendre de lettrés de programmation, mais de cette façon, vous pouvez toujours attendre la coloration syntaxique dans un éditeur, sans lettré de soutien à la programmation.
Il interagit avec le Leiningen, et je crois gâteau, si je n'ai pas essayé moi-même.
Si vous voulez aller entièrement alphabétisée, vous devriez donner org-babel-clojure un coup d'oeil. org-bable est un lettré de la programmation de l'extension à la emacs org-mode.
Si vous souhaitez utiliser nrepl le texte suivant devrait être ajouté à votre .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!"))))))
