Состояние искусства для инструментов документации Clojure [закрыто

Question

За последний год или около того я видел различные объявления в списке обсуждений Clojure и других местах о инструментах для документирования кода Clojure. Они варьируются от полных грамотных систем программирования, таких как Marginalia, и инструмент, используемый для создания книги «Clojure в мелких кусочках» (или даже Emacs Org-Mode), до более обычных решений в стиле Javadoc, таких как Autodoc, и сам Javadoc, которые сами По сообщениям, можно использовать с Clojure. Поиск в Google оказывается разными другими, возможно, некоторые, которые заслуживают большего внимания, и, безусловно, некоторые из которых являются личными утилитами для создания документов. Мой вопрос: каковы лучшие инструменты документации, и каковы их сравнительные сильные и слабые стороны, основанные на вашем опыте, используя их? На сегодняшний день я не использовал никаких инструментов документации и заинтересован в экспериментах с одним или несколькими.

Answer 1

мне действительно нравится Маргиналия Если вы хотите принять что -то вроде грамотного программирования. Marginalia пересекает ваш исходный код и создает версию в формате HTML с комментариями, установленными рядом с кодом в очень четком тексте. Комментарии могут быть отформатированы, что делает для очень читаемого окончательного документа. При просмотре исходного кода, который я написал некоторое время назад, я считаю, что маргиналия действительно помогает. Вот пример, сделанный из самого источника маргинации.

Обратите внимание, что это отличается от исходного рабочего процесса грамотного программирования, где вы напишите файл, и из этого генерируется файл, и исходный код. С Marginalia вы пишете обычный файл исходного кода, и это документация, которая вытащилась из этого. Вывод аналогичен тому, что можно ожидать от грамотного программирования, но таким образом вы все еще можете ожидать, что синтаксис выделяет в редакторе, без какой -либо специальной поддержки грамотного программирования.

Он взаимодействует с Лейнингеном, и я верю, что торт, хотя я не пробовал это сам.

Answer 2

Autodoc это простое место для начала, и это то, что Clojure основной и Clojure вносить производить.

Простой в использовании с Мавен. Анкет Я не уверен, существуют ли плагины для Leiningen или Cake.

Answer 3

Кодокс более недавний генератор документов для Clojure.

Answer 4

Если вы хотите полностью грамочить, вы должны дать Org-Babel-Clojure взгляд. Org-Bebable-это грамотное расширение программирования в EMACS Org-режим.

Если вы хотите использовать NREPL, следует добавить в ваш. EMAC:

(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!"))))))