34

在过去一年左右的时间里，我在 Clojure 讨论列表和其他地方看到了关于记录 Clojure 代码的工具的各种公告。这些范围从像 Marginalia 这样的全面读写编程系统，以及用于创建“Clojure in Small Pieces”（甚至是 emacs org-mode）一书的工具，到更传统的 Javadoc 风格的解决方案，如 Autodoc，以及 Javadoc 本身据报道可以与 Clojure 一起使用。谷歌搜索会出现其他各种情况，也许有一些值得更多关注，当然还有一些只是用于生成文档的个人实用程序。我的问题是什么是最好的文档工具，根据您使用它们的经验，它们的比较优势和劣势是什么？到目前为止，我还没有使用过任何文档工具，并且有兴趣尝试一种或多种工具。

4

4 回答 4

21

我真的很喜欢Marginalia，如果你想采用类似文学编程的方法。Marginalia 会遍历您的源代码，并生成一个 html 格式的版本，并在代码旁边以非常清晰的文本设置注释。评论可以采用 markdown 格式，使最终文档非常易读。在查看我前段时间编写的源代码时，我发现 Marginalia 确实很有帮助。这是由 Marginalia 源本身制作的示例。

请注意，这与原始的识字编程工作流程不同，您将在其中编写文件并从中生成源代码。使用 Marginalia，您可以编写一个常规的源代码文件，并且从中提取出文档。输出类似于人们对 literate 编程的期望，但通过这种方式，您仍然可以在编辑器中期望语法高亮显示，而无需任何特殊的 literate 编程支持。

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

于 2011-03-17T04:09:44.170 回答
12

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

于 2012-08-10T20:44:26.610 回答
11

Autodoc是一个简单的起点，也是 Clojure核心和 Clojure contrib的产物。

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

于 2011-03-17T03:57:44.113 回答
6

如果你想完全识字，你应该看看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!"))))))
于 2011-03-17T06:19:49.253 回答