Clojure文档工具的最新技术

Question

在过去一年左右的时间里,我在Clojure讨论列表和其他关于Clojure代码记录工具的地方看到过各种各样的公告.这些包括像Marginalia这样的全面识字编程系统,以及用于创建"小片中的Clojure"(甚至是emacs组织模式)的书籍,以及更常规的Javadoc式解决方案,如Autodoc和Javadoc本身.据报道,可以与Clojure一起使用.一个谷歌搜索出现了各种其他,也许一些值得更多的关注,并且肯定有些只是用于生成文档的个人工具.我的问题是什么是最好的文档工具,根据您使用它们的经验,它们的比较优势和劣势是什么？到目前为止,我还没有使用任何文档工具,并且有兴趣尝试一个或多个.

Answer 1

我真的很喜欢Marginalia,如果你想采取像识字编程方法.Marginalia遍历您的源代码,并生成一个html格式的版本,并在代码旁边以非常明确的文本设置注释.评论可以标记为格式化,使得最终文档非常易读.在回顾我前段时间写过的源代码时,我发现Marginalia真的很有帮助.这是Marginalia来源本身的一个例子.

请注意,这与原始的文字编程工作流程不同,您可以在其中编写文件并从中生成源代码.使用Marginalia,您可以编写一个常规源代码文件,这是从中获取的文档.输出类似于文字编程所期望的那样,但是这样你仍然可以在编辑器中期望语法高亮,而不需要任何特殊的文字编程支持.

它与Leiningen互操作,我相信蛋糕,虽然我自己没有尝试过.

Answer 2

Autodoc是一个容易入手的地方,也是Clojure 核心和Clojure 贡献的产物.

易于与Maven一起使用.我不确定Leiningen或Cake是否存在插件.

Answer 3

Codox是Clojure最新的文档生成器.

Answer 4

如果你想要完全识字,你应该给org-babel-clojure看一看.org-bable是emacs org-mode的文字编程扩展.

如果你想使用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!"))))))