Question

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

Answer 1

我真的很喜欢Marginalia，如果你想采取类似文字的编程方法。 Marginalia遍历您的源代码，并生成一个html格式的版本，并在代码旁边以非常明确的文本设置注释。评论可以标记为格式化，使得最终文档非常易读。在回顾我前段时间写过的源代码时，我发现Marginalia真的很有帮助。 Here's an example made from the Marginalia source itself

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

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

Answer 2

Autodoc是一个容易上手的地方，也是Clojure core和Clojure contrib所产生的。

易于使用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!"))))))

Clojure文档工具的最新技术

4 个答案: