Clojure文档工具的最新技术 [英] State of the Art for Clojure Documentation Tools

问题描述

在过去的一年左右，我看到了关于Clojure讨论列表和其他地方关于Clojure代码记录工具的各种公告。这些范围包括像Marginalia这样的全面的识字编程系统，用于创建Clojure in Small Pieces（甚至是emacs组织模式）的工具，更为传统的Javadoc样式的解决方案，如Autodoc和Javadoc本身据报道可以与Clojure一起使用。谷歌搜索会产生不同的其他人，也许有几个值得更多的关注，并且肯定有些只是个人实用程序生成文档。我的问题是什么是最好的文档工具，根据你使用它们的经验，他们的比较优势和弱点是什么？我迄今没有使用任何文档工具，并且有兴趣尝试一个或多个。

解决方案

我真的很喜欢 Marginalia ，如果你想采取像识字编程方法。 Marginalia遍历您的源代码，并生成一个html格式的版本，其中的注释设置在一个非常明确的文本中的代码旁边。评论可以被格式化，使得非常可读的最终文件。在审查我之前写过的源代码时，我发现Marginalia真的有帮助。 以下是由Marginalia来源本身制作的示例。

请注意，这与原始的识字编程工作流程不同，您可以在其中编写文件，并从中生成源代码。使用Marginalia，您可以编写一个常规的源代码文件，这是从中删除的文档。输出类似于可读写编程所期望的结果，但是通过这种方式，您仍然可以在编辑器中预期语法高亮，无需任何特殊的识字编程支持。

它互操作与莱宁宁，我相信蛋糕，虽然我还没有尝试过这个。

Over the last year or so I've seen various announcements on the Clojure discussion list and other places about tools for documenting Clojure code. These range from full-on literate programming systems like Marginalia, and the tool being used to create the book "Clojure in Small Pieces" (or even emacs org-mode), to more conventional Javadoc-style solutions like Autodoc, and Javadoc itself which reportedly can be used with Clojure. A google search turns up various others, perhaps a few that deserve more attention, and for sure some that are just personal utilities for generating docs. My question is what are the best documentation tools, and what are their comparative strengths and weaknesses based on your experiences using them? I have not used any documentation tools to date, and am interested in experimenting with one or more.

解决方案

I really like Marginalia if you want to take something like a literate programming approach. Marginalia traverses your source code, and produces an html formatted version with comments set beside code in a very clear text. Comments can be markdown formatted, making for a very readable final document. When reviewing source code that I've written some time ago, I find Marginalia really helps. Here's an example made from the Marginalia source itself.

Note that this differs from the original literate programming workflow, where you would write a file and source code is generated from that. With Marginalia, you write a regular source code file, and it's the documentation that's pulled out of that. The output is similar to what one might expect from literate programming, but this way you can still expect syntax highlighting in an editor, without any special literate programming support.

It interoperates with Leiningen, and I believe cake, though I haven't tried that myself.

这篇关于Clojure文档工具的最新技术的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！