Clojure 文档工具的最新技术[关闭]答案

【问题标题】：State of the Art for Clojure Documentation Tools [closed]Clojure 文档工具的最新技术[关闭]
【发布时间】：2011-07-17 02:41:25
【问题描述】：

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

【问题讨论】：

请注意，Marginalia 并不是一个全面的识字编程工具。它确实在许多方面促进了一种文学风格，但它绝不理解如何处理乱序代码注释，如“Clojure in Small Pieces”中使用的系统。 org-babel-clojure，或 Knuth 的 CWEB。它只是一个方便代码阅读的好工具。
听起来 Autodoc 和 Marginalia 都是 doc-string 驱动的，并且都与 Leiningen 有很好的集成，但主要区别在于 Marginalia 生成更丰富的输出，而 Autodoc 更基础。谢谢！

标签： documentation clojure javadoc literate-programming marginalia

【解决方案1】：

如果你想完全识字，你应该给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!"))))))

【讨论】：

现在 swank-clojure 已被 nrepl 弃用，是否有更新或替代 org-babel-clojure？我正在为 LP 调查 noweb，但在编写/开发期间有一个 repl 会很棒。
org-babel-clojure 很好用。我已经编辑了上面的回复以反映我目前的使用情况。

【解决方案2】：

Codox 是一个更新的 Clojure 文档生成器。

【讨论】：

我保证这是一个不错的选择。 Marginalia 在与文档一起展示代码方面给人留下了深刻的印象，但它的“个性”有点太多，我觉得这会分散注意力。 Codox 据说还支持解析内联 html 和可能的降价，但具有讽刺意味的是，文档太少了，我无法弄清楚（甚至 codox 输出都没有！）

【解决方案3】：

我真的很喜欢Marginalia，如果你想采用类似文学编程的方法。 Marginalia 遍历您的源代码，并生成一个 html 格式的版本，其中 cmets 在代码旁边以非常清晰的文本设置。评论可以采用 markdown 格式，使最终文档非常易读。在查看我前段时间编写的源代码时，我发现 Marginalia 确实很有帮助。 Here's an example made from the Marginalia source itself.

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

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

【讨论】：

我也喜欢边缘化。一个问题是它不能提供很好的索引参考。话又说回来，这并不是它的真正目的。
@Andrew 某种索引正在计划中。 :-)
@fogus - 哦，太好了！这将非常有用。
边缘示例已移动。

【解决方案4】：

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

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

【讨论】：

查看为Autodoc提供的链接，有一段关于autodoc的lein插件：Building Autodoc with Leiningen
我的项目没有使用 clojure.main 主类，因此 autodoc 退出：Error: Could not find or load main class clojure.main。我一直无法找到在 Maven POM 中指定我自己的主类的方法。