Уровень техники для Clojure Инструменты документации

За последний год или около того я видел различные объявления в списке обсуждения Clojure и в других местах о инструментах для документирования кода Clojure. Они варьируются от полных грамотных систем программирования, таких как Marginalia, и инструмента, используемого для создания книги "Clojure в Small Pieces" (или даже emacs org-mode), к более обычным решениям в стиле Javadoc, таким как Autodoc и Javadoc который, как сообщается, может быть использован с Clojure. В поиске Google появляются различные другие, возможно, некоторые, заслуживающие большего внимания, и, наверняка, некоторые из них являются лишь личными утилитами для создания документов. Мой вопрос в том, какие лучшие инструменты для документации, и каковы их сравнительные сильные и слабые стороны, основанные на вашем опыте использования? Я до сих пор не использовал никаких инструментов документации, и мне интересно экспериментировать с одним или несколькими.

Ответ 1

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

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

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

Ответ 2

Autodoc - это простое место для начала и есть то, что Clojure core и Clojure contrib.

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

Ответ 3

Codox - это более поздний генератор документации для Clojure.

Ответ 4

Если вы хотите полностью грамотно, вы должны org-babel- clojure посмотреть. org-bable - это грамотное расширение программирования для org-mode emacs.

Если вы хотите использовать nrepl, к вашему .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!"))))))