État de l'art pour les outils de documentation Clojure [fermé]

Question

Au cours de la dernière année, je l'ai vu plusieurs annonces sur la liste de discussion de Clojure et d'autres endroits sur les outils pour documenter le code Clojure. Celles-ci vont des systèmes de programmation complète sur alphabétisés comme Marginalia, et l'outil utilisé pour créer le livre « Clojure en petits morceaux » (ou même org-mode emacs), aux solutions Javadoc de style plus classiques comme Autodoc, et Javadoc lui-même qui aurait peut être utilisé avec Clojure. Une recherche de Google se présente plusieurs autres, peut-être quelques-uns qui méritent plus d'attention, et que certains qui ne sont que des utilitaires personnels pour générer docs. Ma question est quels sont les meilleurs outils de documentation, et quelles sont leurs forces et leurs faiblesses comparatives en fonction de vos expériences qui les utilisent? Je ne l'ai pas utilisé les outils de documentation à ce jour, et je suis intéressé à expérimenter avec un ou plusieurs.

Answer 1

Je aime vraiment Marginalia si vous voulez prendre quelque chose comme une approche de programmation littéraire. Marginalia parcourt votre code source et produit une version au format HTML avec des commentaires à côté du code dans définis un texte très clair. Les commentaires peuvent être mises en forme démarquage, ce qui pour un document final très lisible. Lors de l'examen du code source que j'ai écrit il y a quelque temps, je trouve Marginalia aide vraiment. Voici un exemple en la source elle-même Marginalia .

Notez que cela diffère du flux de travail de programmation littéraire original, où vous pouvez écrire un fichier et le code source est généré à partir de ce. Avec Marginalia, vous écrivez un fichier régulier de code source, et il est la documentation qui est tirée de cela. La sortie est similaire à ce que l'on pourrait attendre de la programmation littéraire, mais cette façon, vous pouvez toujours attendre la coloration syntaxique dans un éditeur, sans aucun soutien de la programmation littéraire spéciale.

Il interagit avec Leiningen, et je crois que le gâteau, mais je ne l'ai pas essayé moi-même.

Answer 2

Autodoc est un endroit facile à démarrer et est ce que Clojure noyau et Clojure contrib produits .

Facile à utiliser avec Maven . Je ne sais pas si les plugins existent pour Leiningen ou gâteau.

Answer 3

Codox est un générateur de documentation plus récente pour Clojure.

Answer 4

Si vous voulez aller pleinement alphabétisé devrait vous donner org-babel-clojure un coup d'oeil. org-bable est une extension de la programmation littéraire aux emacs org-mode.

Si vous voulez utiliser nrepl les éléments suivants doivent être ajoutés à 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!"))))))