Clojure文档工具的最新技术

Question

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

Answer 1

如果你想采用类似于识字编程的方法，我真的很喜欢Marginalia。边沿遍历你的源代码，并生成一个html格式的版本，在代码旁边用一个非常清晰的文本设置注释。注释可以标记格式，使最终文档具有很强的可读性。当回顾我前段时间写的源代码时，我发现Marginalia真的很有帮助。Here's an example made from the Marginalia source itself。

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

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

Answer 2

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

Answer 3

Autodoc是一个很容易开始的地方，它是Clojure core和Clojure contrib产生的。

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